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

| Lumanu Object             | 1099Policy Resource | Description                                                                  |
|---------------------------|---------------------|------------------------------------------------------------------------------|
| Vendor                    | Contractor          | Must exist before quoting; store Lumanu ID in `custom_metadata`.            |
| Payable / Payout          | Job + Assignment     | Represents work scope and payment window.                                   |
| COI File or URL          | Certificate          | Tracked and validated automatically.                                       |
| Payout Reference          | Invoice (optional)   | Record payment details for reconciliation.                                  |

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

| Lumanu Field             | 1099Policy Contractor         | Notes                                |
|---------------------------|------------------------------|--------------------------------------|
| `vendor.id`              | `custom_metadata.lumanu_vendor_id` | Required for reconciliation            |
| `name`                   | `contact.first_name` / `contact.last_name` | Split if available                  |
| `email`                  | `contact.email` | **Required**; use proxy if hidden   |
| `country`                | `address.country`  | Optional                             |
| `region`                 | `address.region`   | Optional                             |

**Source: Lumanu (REST)**
```plaintext
GET https://api.lumanu.com/v1/vendors/{vendor_id}
Authorization: Bearer lm_live_***
```

**Destination: 1099Policy (POST /contractors)**
```plaintext
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": "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.

| 1099Policy Job           | Lumanu Source                | Notes                                |
|---------------------------|------------------------------|--------------------------------------|
| `name`                   | Payable memo / campaign + vendor handle | Descriptive title                   |
| `description`            | Campaign or work description  | Optional                             |
| `entity`                 | Your internal client/account ID | Must exist                          |
| `category_code`          | Your mapped code (e.g., CREATOR_MARKETING) | Maintain mapping              |
| `wage` (cents)          | Payable or payout amount × 100 | Required                             |
| `wage_type`              | `"flatfee"`                 | Most creator payments are fixed      |
| `region`                 | Country or jurisdiction       | Defaults to contractor home state    |
| `custom_metadata.lumanu_payout_id` | Payout or payable ID | For reconciliation                    |

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

| 1099Policy Quote        | Lumanu Source                | Notes                                |
|---------------------------|------------------------------|--------------------------------------|
| `contractor`             | Mapped vendor                | Must exist first                     |
| `job`                    | Returned Job ID              | Required                             |
| `coverage_type[]`        | Coverage type(s)             | e.g., `["general","workers-comp"]` |
| `effective_date`         | Payout date or work start (epoch UTC) | Required                   |
| `end_date`               | End of service or usage term (epoch UTC) | Optional                       |
| `custom_metadata.lumanu_payout_id` | Payout/Payable ID | For reconciliation                    |

**Destination: 1099Policy (POST /quotes)**
```plaintext
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": { "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)**
```plaintext
POST https://api.1099policy.com/api/v1/apply/sessions
Authorization: Bearer t9k_test_***
Content-Type: application/json
```
```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)**
```plaintext
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": { "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)**
```plaintext
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
}
```

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

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

| Source                     | Event                        | Action                          |
|---------------------------|------------------------------|----------------------------------|
| Lumanu                    | Vendor onboarded            | Create Contractor in 1099Policy |
| Lumanu                    | Payout created/approved      | Create Job + Quote in 1099Policy |
| 1099Policy                | `application.started`        | Mark payout “Coverage in progress.”|
| 1099Policy                | `policy.active`              | Mark payout “Insured.”           |
| 1099Policy                | `policy.canceled` / `policy.expired` | Halt or flag payout         |
| 1099Policy                | `certificate.validated`      | Mark COI valid.                  |
| 1099Policy                | `certificate.flagged`        | Flag payout for review.          |

## 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](https://developers.lumanu.com/docs/quickstart-guide)
- Vendor Onboarding: [https://developers.lumanu.com/docs/vendor-onboarding](https://developers.lumanu.com/docs/vendor-onboarding)
- Payout Lifecycle & Webhooks: [https://help.lumanu.com/en/articles/1501632](https://help.lumanu.com/en/articles/1501632)
- Pre-Funding Flow: [https://developers.lumanu.com/docs/pre-funding-flow](https://developers.lumanu.com/docs/pre-funding-flow)