## Rippling

##### Learn how to connect Rippling’s contractor management API with 1099Policy to automate insurance validation, bind fractional coverage, and synchronize compliance events for every contractor engagement.

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

### Employment type filter

1099Policy integrations must explicitly filter for `employment_type = CONTRACTOR` using Rippling’s People or Employment APIs.

### 3. Core Concepts

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

| Rippling Object | 1099Policy Resource | Description |
| --- | --- | --- |
| Contractor (Person) | Contractor | Must exist before quoting coverage |
| Contract or Engagement | Job + Assignment | Defines scope, pay, and coverage period |
| Document (COI) | Certificate | Optional—used for validation |
| Payment / Invoice | Invoice | Optional—records final remuneration |
| Identifiers (`person_id`, `contract_id`) | `custom_metadata.*` | Used for reconciliation only |

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

| Rippling Field | 1099Policy Contractor | Notes |
| --- | --- | --- |
| `person.id` | `custom_metadata.rippling_person_id` | Reconciliation key |
| `first_name`, `last_name` | `contact.first_name`, `contact.last_name` | Required |
| `email` | `contact.email` | **Required**; use proxy if hidden |
| `country` | `address.country` | Optional |
| `region` | `address.region` | Optional |

**Source: Rippling (REST)**  
```bash
GET https://api.rippling.com/v1/people/{person_id}
Authorization: Bearer YOUR_RIPPLING_TOKEN
```

**Destination: 1099Policy (POST /contractors)**  
```bash
POST https://api.1099policy.com/api/v1/contractors
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json
Idempotency-Key: rippling-person-<PERSON_ID>
```

```json
{
  "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.

| 1099Policy Job Field | Rippling Source | Notes |
| --- | --- | --- |
| `name` | Contract title or role name | Descriptive title |
| `description` | Engagement or project summary | Optional |
| `entity` | Your internal client/account ID | Must exist in 1099Policy |
| `category_code` | Contractor type → mapped category | Maintain mapping table |
| `wage` (cents) | `rate.amount × 100` | Required |
| `wage_type` | Derived from `rate.type` | "hourly" or "flatfee" |
| `region` | Work region or contractor address | Defaults to contractor’s region |
| `custom_metadata.contract_id` | Rippling Contract ID | Required |
| `custom_metadata.person_id` | Person ID | Optional |

**Source: Rippling (REST)**  
```bash
GET https://api.rippling.com/v1/contracts/{contract_id}
Authorization: Bearer YOUR_RIPPLING_TOKEN
```

**Destination: 1099Policy (POST /jobs)**  
```bash
POST https://api.1099policy.com/api/v1/jobs
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json
```

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

```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)**  
```bash
POST https://api.1099policy.com/api/v1/apply/sessions
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json
```

```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)**  
```bash
POST https://api.1099policy.com/api/v1/assignments
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json
```

```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)**  
```bash
POST https://api.1099policy.com/api/v1/invoices
Authorization: Bearer YOUR_1099POLICY_TOKEN
Content-Type: application/json
```

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

| Source | Event | Action |
| --- | --- | --- |
| Rippling | `contract.created` or `contract.updated` | Create Job + Quote in 1099Policy |
| Rippling | `invoice.created` | Record invoice |
| 1099Policy | `policy.active` | Mark contractor insured |
| 1099Policy | `policy.canceled` / `policy.expired` | Clear or flag contractor compliance |
| 1099Policy | `certificate.validated` | Mark COI valid |
| 1099Policy | `certificate.flagged` | Trigger review process |

## 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](https://developer.rippling.com/documentation/rest-api)
- Data Models (Employment Types): [https://developer.rippling.com/documentation/rest-api/essentials/data-models](https://developer.rippling.com/documentation/rest-api/essentials/data-models)
- People API: [https://developer.rippling.com/reference/get-people](https://developer.rippling.com/reference/get-people)
- Contracts API: [https://developer.rippling.com/reference/get-contracts](https://developer.rippling.com/reference/get-contracts)