Freelancer Fractional Insurance Integration | 1099Policy

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:

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.

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)

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.

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)

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

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:

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" }
}

Unix timestamp

Use Unix seconds (UTC) for paycycle_startdate and paycycle_enddate.

See full API reference: 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

7. References