1. Overview

Connect Rippling’s contractor management data to 1099Policy so each contractor engagement is properly insured or has a validated Certificate of Insurance (COI) before work begins.

You can:

• Bind fractional, on-demand coverage for Rippling contractor engagements.
• Automatically validate or upload COIs for compliance tracking.
• Keep compliance in sync via 1099Policy webhooks (policy.*, certificate.*).
• Map Rippling contractor pay to 1099Policy job.wage (in cents) and wage_type.
• Persist Rippling IDs (e.g., person_id, contract_id, invoice_id) in custom_metadata for reconciliation.

2. Integration Timing & Trigger

Coverage should begin when a contractor engagement or payment is finalized. Rippling’s Contractor API provides status changes when contracts are created or updated—ideal moments to trigger 1099Policy coverage workflows.

• Primary trigger: Contractor engagement created or finalized.
• Alternative triggers: Invoice created or payment scheduled.
• Event delivery: Rippling Webhooks (configured per API key).
• Required data: person_id, employment_type=CONTRACTOR, contract_id, rate.amount, rate.type, start_date, end_date.

3. Core Concepts

Each Rippling object maps to a corresponding 1099Policy resource to maintain contractor coverage, documentation, and audit trails.

4. End-to-End Implementation

Follow these steps to integrate Rippling and 1099Policy for automated contractor coverage.

4.1 Create Contractor

Each Rippling contractor must exist in 1099Policy before creating Quotes or Assignments. Include a unique email address for tenant-level uniqueness. Generate a proxy if Rippling does not expose one (e.g., <person_id>@relay.yourdomain.com).

Source: Rippling (REST)

GET https://api.rippling.com/v1/people/{person_id}
Authorization: Bearer YOUR_RIPPLING_TOKEN

Destination: 1099Policy (POST /contractors)

POST https://api.1099policy.com/api/v1/contractors
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json
Idempotency-Key: rippling-person-<PERSON_ID>

{
  "contact": {
    "first_name": "Alex",
    "last_name": "Morgan",
    "email": "person_8831@relay.yourdomain.com"
  },
  "address": {
    "country": "US",
    "region": "CA"
  },
  "custom_metadata": {
    "rippling_person_id": "per_8831"
  }
}

4.2 Create Job

Create a Job to represent each contractor engagement’s scope and compensation structure.

Source: Rippling (REST)

GET https://api.rippling.com/v1/contracts/{contract_id}
Authorization: Bearer YOUR_RIPPLING_TOKEN

Destination: 1099Policy (POST /jobs)

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

{
  "name": "Freelance Design Contract — Q4 Assets",
  "description": "Contract for creative production and deliverables",
  "entity": "en_12AbC3",
  "category_code": "MARKETING_DESIGN",
  "wage": 800000,
  "wage_type": "flatfee",
  "region": "US",
  "custom_metadata": {
    "rippling_contract_id": "ct_5G89a",
    "rippling_person_id": "per_8831"
  }
}

4.3 Create Quote

Quotes define the coverage duration and insurance type for each engagement.

Destination: 1099Policy (POST /quotes)

POST https://api.1099policy.com/api/v1/quotes
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json

{
  "contractor": "cn_Kh18Qs",
  "job": "jb_Dl9n42",
  "coverage_type": ["general","workers-comp"],
  "effective_date": 1764300000,
  "end_date": 1766892000,
  "custom_metadata": { "rippling_contract_id": "ct_5G89a" }
}

4.4 Create Insurance Application Session

Redirect contractors to complete their first policy opt-in and bind coverage.

Destination: 1099Policy (POST /apply/sessions)

POST https://api.1099policy.com/api/v1/apply/sessions
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json

{
  "quote": "qt_Pf5LmA",
  "success_url": "https://app.rippling.com/contracts/ct_5G89a?coverage=active",
  "cancel_url": "https://app.rippling.com/contracts/ct_5G89a?coverage=canceled",
  "custom_metadata": { "rippling_contract_id": "ct_5G89a" }
}

4.5 Create Assignment

Assignments automatically bind coverage for returning contractors who have already opted in.

Destination: 1099Policy (POST /assignments)

POST https://api.1099policy.com/api/v1/assignments
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json

{
  "contractor": "cn_Kh18Qs",
  "job": "jb_Dl9n42",
  "effective_date": 1764300000,
  "end_date": 1766892000,
  "coverage_type": ["general","workers-comp"],
  "custom_metadata": { "rippling_contract_id": "ct_5G89a" }
}

4.6 Upload Certificate (BYO-COI)

This independent workflow supports contractors who already have their own insurance. Upload the COI for validation and compliance tracking.

Destination: 1099Policy (POST /files/certificates)
(multipart upload)

Fields:

• certificate=@file.pdf
• contractor=cn_Kh18Qs
• custom_metadata[rippling_contract_id]=ct_5G89a

4.7 Record Invoice (Optional)

If the contractor’s final payment differs from the contract amount, record it for reconciliation. This step does not affect insurance coverage.

Destination: 1099Policy (POST /invoices)

POST https://api.1099policy.com/api/v1/invoices
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json

{
  "contractor": "cn_ti8eXviE4A",
  "job": "jb_rajdrwMUKi",
  "gross_pay": 1200,
  "paycycle_startdate": 1714419793,
  "paycycle_enddate": 1714419793
}

5. Webhooks

Rippling and 1099Policy both provide webhook systems to synchronize engagement, payment, and insurance events.

6. Testing Checklist

• Contractor created with proxy email if missing
• Job created with mapped compensation fields
• Quote created with coverage window and types
• Apply Session completed successfully
• Assignment aligns with contract term
• COI uploads validated
• Optional invoice recorded
• Webhook retries handled with idempotency

7. References

• Rippling REST API: https://developer.rippling.com/documentation/rest-api
• Data Models (Employment Types): https://developer.rippling.com/documentation/rest-api/essentials/data-models
• People API: https://developer.rippling.com/reference/get-people
• Contracts API: https://developer.rippling.com/reference/get-contracts