Description

Field Nation is a field service management platform that connects businesses with skilled on-site technicians, enabling companies to post work orders, manage assignments, and process payments for contract-based service work.

### Products

- Fractional Insurance
- Automated Certificate Review

### 1099Policy Resources

- [Quick Start Guide](/content/docs/quick-start/index.html) 
- [API Reference](/content/docs/quick-start/index.html)

---

## Field Nation Integration Guide

##### Learn how to connect Field Nation work orders to 1099Policy to verify technician coverage instantly and offer fractional insurance for every on-site service job.

## 1. Overview

Connect Field Nation’s Work Order data to 1099Policy to ensure that every Provider (technician) has valid insurance coverage before work begins. This integration automates policy binding, certificate validation, and compliance updates between both systems.

By connecting Field Nation and 1099Policy, you can:

- Bind on-demand coverage as soon as a Provider is assigned
- Automatically verify or upload Certificates of Insurance (COIs)
- Sync compliance statuses through 1099Policy webhooks (`policy.*`, `certificate.*`)
- Map pay rates or funded amounts to `job.wage` (in cents) and `wage_type`
- Persist the Field Nation Work Order ID in `custom_metadata.work_order_id` for reconciliation

## 2. Integration Flow

Coverage should activate as soon as a Provider is assigned so compliance is confirmed before on-site work begins.

- **Primary trigger:** `workorder.status.assigned` — subscribe via Field Nation’s Webhooks API
- **Alternative trigger:** `workorder.created` — prepare coverage when the Work Order is posted
- **Payload:** The webhook delivers the full Work Order object, including schedule, provider, pay, and location details
- **Auth & endpoints:** Use OAuth 2.0 (`?access_token=`) with
  - Sandbox: `https://api-sandbox.fndev.net/api/rest/v2/`
  - Production: `https://api.fieldnation.com/api/rest/v2/`

## 3. Core Concepts

Each Field Nation object maps directly to a 1099Policy coverage concept. This ensures consistency between compliance tracking and insurance binding.

| Field Nation Object | 1099Policy Object | Description |
| --- | --- | --- |
| Work Order | Job + Assignment | Job defines scope and pay; Assignment applies coverage to scheduled dates |
| Provider | Contractor | Represents the insured individual |
| COI Upload | Certificate | BYO-COI intake and validation |
| Work Order ID | `custom_metadata.work_order_id` | Reconciliation key |

## 4. End-to-End Implementation

This section walks through the complete lifecycle, showing how to retrieve data from Field Nation and create coverage records in 1099Policy.

### 4.1 Create Contractor

Each Provider must exist as a Contractor in 1099Policy before creating a quote. Each Contractor must include a unique `contact.email` within your tenant. If Field Nation does not expose the Provider’s email, generate a proxy such as `<provider.id>@relay.yourdomain.com`.

| Field Nation Field | 1099Policy Contractor | Notes |
| --- | --- | --- |
| `provider.id` | `custom_metadata.fieldnation_provider_id` | Reconciliation key |
| `provider.first_name` / `last_name` | `contact.first_name`, `contact.last_name` | Required |
| `provider.email` | `contact.email` | **Required**; use proxy if missing |
| `provider.location.country` | `address.country` | Optional |
| `provider.location.state` / `city` | `address.region` / `address.city` | Optional |

**Source: Field Nation (REST)**

GET https://api.fieldnation.com/api/rest/v2/users/{providerId}?access_token=...

**Destination: 1099Policy (POST /contractors)**

POST https://api.1099policy.com/api/v1/contractors
    Authorization: Bearer t9k_test_***
    Content-Type: application/json
    Idempotency-Key: fn-provider-<PROVIDER_ID>

```json
{
  "contact": {
    "first_name": "Jordan",
    "last_name": "Lee",
    "email": "987654@relay.yourdomain.com"
  },
  "address": {
    "country": "US",
    "region": "TX",
    "city": "Dallas"
  },
  "custom_metadata": {
    "fieldnation_provider_id": "987654"
  }
}
```

### 4.2 Create Job

Jobs describe the work being performed, its compensation, and category. Create a Job when a Work Order is assigned to a Provider.

| 1099Policy Job Field | Field Nation Source | Notes |
| --- | --- | --- |
| `name` | Work Order `title` | Role or task name |
| `description` | Work Order `description` | Scope of work |
| `entity` | Your internal client/account ID | Must exist in 1099Policy |
| `category_code` | Work Order `category` or `work_type` → mapped code | Maintain mapping |
| `wage` (cents) | Pay object `amount × 100` | Required |
| `wage_type` | Pay Rate type → "hourly" or "flatfee" | Required |
| `region` | Work Order location `state` | Defaults to contractor location |
| `custom_metadata.work_order_id` | Work Order `id` | Reconciliation key |

**Source: Field Nation (REST)**

GET https://api.fieldnation.com/api/rest/v2/workorders/{id}?access_token=...
    GET https://api.fieldnation.com/api/rest/v2/workorders/{id}/pay?access_token=...

**Destination: 1099Policy (POST /jobs)**

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

```json
{
  "name": "WO 88342 — Network Install",
  "description": "On-site router installation and testing",
  "entity": "en_a12B3C4",
  "category_code": "NETWORK_INSTALL",
  "wage": 6500,
  "wage_type": "hourly",
  "region": "TX",
  "custom_metadata": { "work_order_id": "88342" }
}
```

### 4.3 Create Quote

Quotes determine the policy type and coverage duration for the Work Order. Use the Provider’s Contractor record, Job ID, and Work Order schedule.

| 1099Policy Quote Field | Field Nation Source | Notes |
| --- | --- | --- |
| `contractor` | Provider → Contractor mapping | Must exist first |
| `job` | Returned Job ID | Required |
| `coverage_type[]` | Compliance requirements | e.g., `['workers-comp','general']` |
| `effective_date` | Work Order schedule start (epoch UTC) | Required |
| `end_date` | Work Order schedule end (epoch UTC) | Required |
| `custom_metadata.work_order_id` | Work Order `id` | Reconciliation key |

**Source: Field Nation (REST)**

GET https://api.fieldnation.com/api/rest/v2/workorders/{id}/schedule?access_token=...

**Destination: 1099Policy (POST /quotes)**

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

```json
{
  "contractor": "cn_2Hk3a91",
  "job": "jb_7ZfXqP9",
  "coverage_type": ["workers-comp","general"],
  "effective_date": 1764585600,
  "end_date": 1764672000,
  "custom_metadata": { "work_order_id": "88342" }
}
```

### 4.4 Create Insurance Application Session

Create an Application Session for first-time Providers so they can review and bind coverage.

**Destination: 1099Policy (POST /apply/sessions)**

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

```json
{
  "quote": "qt_Ya42GhT",
  "success_url": "https://fieldnation.com/workorders/88342?coverage=active",
  "cancel_url": "https://fieldnation.com/workorders/88342?coverage=canceled",
  "custom_metadata": { "work_order_id": "88342" }
}
```

One time opt-in

Providers complete this flow once to activate their first policy.

### 4.5 Create Assignment

Assignments apply coverage automatically for returning Providers who already completed their initial opt-in.

**Destination: 1099Policy (POST /assignments)**

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

```json
{
  "contractor": "cn_2Hk3a91",
  "job": "jb_7ZfXqP9",
  "effective_date": 1764585600,
  "end_date": 1764672000,
  "coverage_type": ["workers-comp","general"],
  "custom_metadata": { "work_order_id": "88342" }
}
```

### 4.6 Upload Certificate (BYO-COI)

If a Provider uploads their own COI to Field Nation, forward it to 1099Policy for automated validation.

**Source: Field Nation (REST)**

GET https://api.fieldnation.com/api/rest/v2/workorders/{id}/attachments?access_token=...

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

Fields:

- `certificate=@file.pdf`
- `contractor=cn_2Hk3a91`
- `custom_metadata[work_order_id]=88342`

General liability option

Field Nation also allows Providers to purchase its in-platform general liability option if no COI is uploaded.

### 4.7 Record Invoice (Optional)

If the contractor’s final pay differs from the original estimate, record the actual remuneration for reconciliation and audit. This step is optional and does not affect insurance coverage.

**Destination: 1099Policy (POST /invoices)**

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

Webhooks keep both systems synchronized throughout the Work Order lifecycle.

| Source | Event | Action |
| --- | --- | --- |
| Field Nation | `workorder.status.assigned` | Create Job and Quote; if first-time, create Application Session |
| Field Nation | `schedule.updated` / `provider.checked_in/out` | Adjust Assignment window |
| Field Nation | `workorder.status.work_done` / `approved` | End coverage |
| 1099Policy | `policy.active` | Mark Provider insured |
| 1099Policy | `policy.expired` / `policy.canceled` | Mark coverage inactive |
| 1099Policy | `certificate.validated` | Mark COI valid |
| 1099Policy | `certificate.flagged` | Flag for manual review |

## 6. Testing Checklist

Use this checklist to confirm that your integration behaves as expected.

- Provider created with proxy email if missing
- Job created with correct wage and metadata
- Quote created and session launches successfully
- Application Session completes and coverage binds
- Assignment dates align with Work Order schedule
- Webhook endpoint verified with signature
- Certificate uploads trigger validation

## 7. References

- [Field Nation API Documentation](https://developer.fieldnation.com/api/v1/docs/)
- [Webhooks Events and Status Changes](https://developer.fieldnation.com/client-api/webhooks/events/)
- [OAuth 2.0 and Authentication Guide](https://developer.fieldnation.com/api/v1/docs/#authentication)