Lumanu Integration Guide

Learn how to integrate Lumanu with 1099Policy to automate fractional insurance for creator/contractor payouts, validate COIs, and trigger coverage in real time.

1. Overview

Connect Lumanu vendor (creator/freelancer) payouts to 1099Policy to ensure every engagement has valid insurance coverage or a verified Certificate of Insurance (COI) before funds are disbursed.

You can:

• Bind on-demand, fractional coverage tied to a payout or payable.
• Automatically validate and track COIs in 1099Policy.
• Keep compliance synced using 1099Policy webhooks (policy.*, certificate.*).
• Map Lumanu payout data to 1099Policy job.wage (in cents) and wage_type (flatfee).
• Store Lumanu IDs only in custom_metadata (never as resource IDs).

2. Integration Timing & Trigger

Insurance coverage should activate before payouts are released. The best signal is when a payable or payout is created, indicating funds are scheduled or ready.

• Primary trigger: When a vendor completes onboarding and receives a permanent Lumanu ID (use that event to pre-create the 1099Policy Contractor).
• Funding note: For pre-funding workflows, trigger coverage when the payable is created, i.e., payable.created.

3. Core Concepts

Each Lumanu object maps directly to a 1099Policy resource, ensuring payout-related coverage is accurate and reconciled.

4. End-to-End Implementation

4.1 Create Contractor

Each Lumanu Vendor must exist in 1099Policy before creating a Quote or Assignment. Include a unique email address—generate a proxy if Lumanu doesn’t expose one.

Source: Lumanu (REST)

GET https://api.lumanu.com/v1/vendors/{vendor_id}
Authorization: Bearer lm_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": "lv_9q2m7@relay.yourdomain.com"
  },
  "address": {
    "country": "US",
    "region": "CA"
  },
  "custom_metadata": {
    "lumanu_vendor_id": "lv_9q2m7"
  }
}

4.2 Create Job

Create a Job to represent the payout’s scope and compensation.

Destination: 1099Policy (POST /jobs)

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

{
  "name": "Creator Payout — Campaign Spring Launch",
  "description": "IG reel + TikTok; content usage 30 days",
  "entity": "en_12AbC3",
  "category_code": "jc_12AbC3",
  "wage": 150000,
  "wage_type": "flatfee",
  "region": "US",
  "custom_metadata": {
    "lumanu_vendor_id": "lv_9q2m7",
    "lumanu_payout_id": "lp_8fz1c"
  }
}

4.3 Create Quote

Quotes define the coverage requirements for a Job.

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": { "lumanu_payout_id": "lp_8fz1c" }
}

4.4 Create Insurance Application Session

Redirect vendors to confirm 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://dashboard.yourdomain.com/vendors/lv_9q2m7?coverage=active",
  "cancel_url": "https://dashboard.yourdomain.com/vendors/lv_9q2m7?coverage=canceled",
  "custom_metadata": { "lumanu_payout_id": "lp_8fz1c" }
}

4.5 Create Assignment

Assignments apply coverage automatically for returning vendors who have already completed their opt-in for a payout or service period.

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": { "lumanu_payout_id": "lp_8fz1c" }
}

4.6 Upload Certificate (BYO-COI)

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

Fetching documents from Freelancer

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

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)

If the payout amount changes or you want to log final remuneration, record it using the Invoice API.

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. See full API reference: https://docs.1099policy.com/group/endpoint-invoice

5. Webhooks

Integrate Lumanu and 1099Policy webhooks to sync payout and insurance events.

6. Testing Checklist

• Contractor exists in 1099Policy (with proxy email if needed)
• Job created with wage + type, and Lumanu IDs in custom_metadata
• Quote created with coverage types + valid dates
• Apply Session redirects and completes binding
• Assignment active for the payout window
• Certificate uploads trigger validation events
• Optional invoice recorded for reconciliation

7. References

• Lumanu API Quickstart: https://developers.lumanu.com/docs/quickstart-guide
• Vendor Onboarding: https://developers.lumanu.com/docs/vendor-onboarding
• Payout Lifecycle & Webhooks: https://help.lumanu.com/en/articles/1501632
• Pre-Funding Flow: https://developers.lumanu.com/docs/pre-funding-flow