## Freelancer Integration Guide

##### Learn how to automate insurance coverage and COI validation for Freelancer.com projects and milestone payments using the 1099Policy API.

## 1. Overview

Connect **Freelancer.com projects and milestone payments** to 1099Policy so every engagement has the right insurance coverage or a verified Certificate of Insurance (COI) before funds are released.

You can:

- Bind on-demand, fractional coverage tied to each project or milestone.
- Validate COIs uploaded by contractors or received externally.
- Keep compliance synced through 1099Policy webhooks (`policy.*`, `certificate.*`).
- Map Freelancer **project budgets and milestones** to `job.wage` (in cents) and `wage_type` (`flatfee` or `hourly`).
- Store Freelancer IDs only in `custom_metadata` (never as resource IDs).

## 2. Integration Timing & Trigger

Coverage should activate as soon as a project hire occurs or a milestone payment is created.

That ensures contractors are insured before beginning work or receiving payment.

- **Primary trigger:** A **hire event** (project accepted) or **milestone created/approved**.
- **Alternative trigger:** A **project update** that finalizes compensation.
- **Event delivery:** Subscribe to [Freelancer Webhooks](https://developers.freelancer.com/docs/webhooks/) for `project`, `bid`, or `milestone` events.
- **Required data:** `project.id`, `user.id`, `budget.amount`, and milestone dates.

## 3. Core Concepts

Each Freelancer object maps to a 1099Policy resource for precise coverage and reconciliation.

| Freelancer Object  | 1099Policy Resource | Description |
|--------------------|---------------------|-------------|
| User (freelancer)  | Contractor           | Must exist before quoting; use `custom_metadata.freelancer_user_id`. |
| Project             | Job + Assignment     | Captures scope, rate, and work period. |
| Milestone Payment   | Invoice (optional)   | Record payment for reconciliation. |
| Document Upload     | Certificate (BYO-COI)| COI managed outside Freelancer API. |

## 4. End-to-End Implementation

### 4.1 Create Contractor

Each Freelancer **User** must exist in 1099Policy before a Quote or Assignment can be created.

If Freelancer does not expose an email, generate a proxy (e.g., `freelancer_{id}@relay.yourdomain.com`).

| Freelancer Field | 1099Policy Contractor | Notes |
|------------------|-----------------------|-------|
| `user.id`       | `custom_metadata.freelancer_user_id` | Required for reconciliation |
| `display_name`  | `contact.first_name` / `contact.last_name` | Split if possible |
| `public_name`   | `contact.first_name`  | Fallback |
| `email`         | `contact.email`       | **Required**; generate proxy if not available |
| `location.country` | `address.country`   | Optional |

**Source: Freelancer (REST)**

```bash
GET https://www.freelancer.com/api/users/0.1/users/{user_id}/
Authorization: Bearer fl_live_***
```

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

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

```json
{
  "contact": {
    "first_name": "Taylor",
    "last_name": "Reed",
    "email": "freelancer_9982@relay.yourdomain.com"
  },
  "address": {
    "country": "US"
  },
  "custom_metadata": {
    "freelancer_user_id": "9982"
  }
}
```

### 4.2 Create Job

Create a **Job** to represent the project scope and compensation from Freelancer.

| 1099Policy Job  | Freelancer Source | Notes |
|------------------|------------------|-------|
| `name`           | `project.title`  | Human-readable project name |
| `description`    | `project.description` | Scope of work |
| `entity`         | Your client/account ID | Must exist in 1099Policy |
| `category_code`  | `project.job.category` → map | Maintain mapping table |
| `wage` (cents)   | `budget.amount × 100` | Required |
| `wage_type`      | `budget.type` → `flatfee` or `hourly` | Required |
| `region`         | `location.country` | Defaults to contractor home state |
| `custom_metadata.project_id` | `project.id` | For reconciliation |

**Source: Freelancer (REST)**

```bash
GET https://www.freelancer.com/api/projects/0.1/projects/{project_id}/
Authorization: Bearer fl_live_***
```

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

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

```json
{
  "name": "Website Redesign for Marketing Team",
  "description": "Refresh homepage and add campaign landing page templates.",
  "entity": "en_12AbC3",
  "category_code": "jc_12AqBu",
  "wage": 250000,
  "wage_type": "flatfee",
  "region": "US",
  "custom_metadata": {
    "freelancer_project_id": "54321"
  }
}
```

### 4.3 Create Quote

Create a **Quote** to define coverage requirements.

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

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

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

### 4.4 Create Insurance Application Session

Redirect freelancers to complete their first policy opt-in and bind coverage using the insurance application session endpoint.

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

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

```json
{
  "quote": "qt_Pf5LmA",
  "success_url": "https://www.freelancer.com/projects/54321?coverage=active",
  "cancel_url": "https://www.freelancer.com/projects/54321?coverage=canceled",
  "custom_metadata": { "freelancer_project_id": "54321" }
}
```

### 4.5 Create Assignment

Assignments apply coverage automatically for returning freelancers who have already completed their opt-in for the project or milestone.

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

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

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

### 4.6 Upload Certificate (BYO-COI)

This is a standalone workflow for freelancers who already hold insurance.

Fetching documents from Freelancer

Freelancer does **not** provide a dedicated COI document endpoint—upload COIs via your platform UI/intake or request them directly from the freelancer.

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

(multipart upload)

Form fields:

- `certificate=@file.pdf`
- `contractor=cn_Kh18Qs`
- `custom_metadata[freelancer_project_id]=54321`

### 4.7 Record Invoice (Optional)

When project payouts differ from the original budget or you want to reconcile final payment data, record it using the 1099Policy Invoice API.

**Source: Freelancer (REST)**

```bash
GET https://www.freelancer.com/api/payments/0.1/milestones/{milestone_id}/
Authorization: Bearer fl_live_***
```

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

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

```json
{
  "contractor": "cn_ti8eXviE4A",
  "job": "jb_rajdrwMUKi",
  "gross_pay": 1200,
  "paycycle_startdate": 1714419793,
  "paycycle_enddate": 1714419793,
  "custom_metadata": { "freelancer_milestone_id": "90123" }
}
```

Unix timestamp

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

See full API reference: [https://docs.1099policy.com/group/endpoint-invoice](https://docs.1099policy.com/group/endpoint-invoice)

## 5. Webhooks

| Source       | Event                            | Action                          |
|--------------|----------------------------------|---------------------------------|
| Freelancer    | `project.hired` or `milestone.created` | Create Job + Quote                  |
| Freelancer    | `payment.released`              | Record invoice                    |
| 1099Policy    | `application.started`           | Mark “Coverage in progress.”     |
| 1099Policy    | `policy.active`                 | Mark “Insured.”                  |
| 1099Policy    | `policy.canceled` / `policy.expired` | Flag project for rebind.       |
| 1099Policy    | `certificate.validated`         | Mark COI valid.                 |
| 1099Policy    | `certificate.flagged`           | Flag for manual review.          |

## 6. Testing Checklist

- Contractor exists and is mapped correctly.
- Job created with correct `wage` and `wage_type`.
- Quote created with valid coverage types and dates.
- Apply Session redirects and binds coverage.
- Assignment aligns with project duration.
- COI upload workflow validated separately.
- Invoice recording confirmed for milestone payments.
- Webhook signatures verified and idempotent.

## 7. References

- **Freelancer API Docs:** [https://developers.freelancer.com/docs/](https://developers.freelancer.com/docs/)
- **Creating a Project (Use Case):** [https://developers.freelancer.com/docs/use-cases/creating-a-project](https://developers.freelancer.com/docs/use-cases/creating-a-project)
- **Freelancer Milestones API:** [https://developers.freelancer.com/docs/api/payments/milestones](https://developers.freelancer.com/docs/api/payments/milestones)