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 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.

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).

Source: Freelancer (REST)

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

Destination: 1099Policy (POST /contractors)

POST https://api.1099policy.com/api/v1/contractors
Authorization: Bearer t9k_test_***
Content-Type: application/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.

Source: Freelancer (REST)

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

Destination: 1099Policy (POST /jobs)

POST https://api.1099policy.com/api/v1/jobs
Authorization: Bearer t9k_test_***
Content-Type: application/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)

POST https://api.1099policy.com/api/v1/quotes
Authorization: Bearer t9k_test_***
Content-Type: application/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)

POST https://api.1099policy.com/api/v1/apply/sessions
Authorization: Bearer t9k_test_***
Content-Type: application/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 for the project or milestone.

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": ["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.

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)

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

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,
  "custom_metadata": { "freelancer_milestone_id": "90123" }
}

5. Webhooks

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/
• Creating a Project (Use Case): https://developers.freelancer.com/docs/use-cases/creating-a-project
• Freelancer Milestones API: https://developers.freelancer.com/docs/api/payments/milestones