# General Opt-In Application

Learn how contractors can complete an insurance application without a specific job assignment.

## Overview

General opt-in applications enable contractors to complete their insurance application **before** they are assigned to a specific job or shift. This workflow is useful when contractors work across multiple job categories or when job assignments are created only after a contractor has opted into coverage.

A general opt-in application is not tied to a job, job category, or engagement. Once the application is complete, coverage can be automatically bound when an assignment is created, without requiring the contractor to reapply.

## When to Use General Opt-In

Use the general opt-in workflow when:

- Contractors join your platform before job opportunities are available.
- Assignments are created dynamically and may span multiple job categories.
- You want contractors to complete the insurance application process once during onboarding.
- Contractors frequently take short or intermittent assignments across various job types.

Use the standard job-specific workflow when:

- Applications must be tied to a specific job or job category.
- Requirements must be quoted and bound in a single workflow tied to the engagement.

## Workflow Overview

A general opt-in application follows this sequence:

1. Create a contractor
2. Create a general opt-in application session  
   - Specify the contractor  
   - Provide redirect URLs  
   - Set `is_general_opt_in = true`  
   - Specify the work state
3. Contractor completes the application
4. Create assignments

The contractor does not submit a separate application for each job.

## Requirements and Constraints

General opt-in applications are currently available with the following limitations:

- **Premium withholding required** (`withhold_premium = true`)
- **Coverage restriction**: Workers’ compensation only
- **State-specific applications**
- **Eligibility conditions**:
  - Application status must be `APPLICATION_COMPLETE`
  - Work state must match the job’s work state
  - Job category must be approved
  - Assignment must request workers’ compensation

## Coverage Binding Logic

When you create an assignment for a contractor with a completed general opt-in application:

1. The system checks for a completed general opt-in for the assignment’s work state.
2. If found, the system checks for existing matching coverage.
3. If matching coverage exists, it is reused.
4. If not, new coverage is automatically bound.
5. If eligibility does not match, the system falls back to the standard workflow.

## Implementing General Opt-In

### Step 1: Create a Contractor

```python
contractor = ten99policy.Contractors.create(
    first_name="Jane",
    last_name="Doe",
    email="jane.doe@example.com",
    phone="5551234567",
    address={
        "line1": "123 Main St",
        "locality": "San Francisco",
        "region": "CA",
        "postalcode": 94102
    }
)
```

### Step 2: Create a General Opt-In Application Session

```python
session = ten99policy.InsuranceApplicationSessions.create(
    contractor=contractor["id"],
    success_url="https://yourapp.com/success",
    cancel_url="https://yourapp.com/cancel",
    is_general_opt_in=True,
    work_state="CA"
)
```

### Step 3: Contractor Completes the Application

The contractor reviews their information, answers application questions and signs documents.

### Step 4: Create Assignments

```python
assignment = ten99policy.Assignments.create(
    contractor=contractor["id"],
    job="jb_ABC123",
    coverage_type=["workers-comp"],
    effective_date=1701561600,
    end_date=1701907200
)
```

The system determines whether to reuse existing coverage, bind new coverage, or fall back to standard matching.

## Fallback and Error Handling

- **No general opt-in found**: Standard workflow applies.
- **Eligibility mismatch**: Standard workflow applies.
- **Coverage binding failure**: Assignment still succeeds; standard workflow applies.
- **Job category restrictions**: Eligibility fails; standard workflow applies.

## State Management

If contractors work in multiple states, you may track general opt-in applications:

```json
{
  "contractor_id": "cn_123",
  "general_opt_in_sessions": [
    {
      "session_id": "ias_CA",
      "work_state": "CA",
      "status": "APPLICATION_COMPLETE"
    },
    {
      "session_id": "ias_NY",
      "work_state": "NY",
      "status": "APPLICATION_COMPLETE"
    }
  ]
}
```

## Comparison: General Opt-In vs. Standard Workflow

| Aspect | General Opt-In | Standard Workflow |
| --- | --- | --- |
| Job required at application | No | Yes |
| Coverage binding | Automatic at assignment creation | Quoted and bound per job |
| Job category flexibility | Works across categories | Tied to specified category |
| Reuse existing coverage | Yes | Yes |
| Use case | Onboarding, multi-category work | Single job-specific coverage |

## Best Practices

- Create general opt-in sessions during onboarding.
- Create separate opt-ins for each state where a contractor may work.
- Monitor assignment eligibility responses.
- Always specify `coverage_type` when creating assignments.
- Ensure job categories are approved.

## API Reference

### Create General Opt-In Session

**POST**`/api/v1/apply/sessions`

```json
{
  "contractor": "cn_123",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "is_general_opt_in": true,
  "work_state": "CA"
}
```

### List General Opt-In Sessions

`GET /api/v1/apply/sessions?contractor={id}&is_general_opt_in=true`

### Create Assignment

**POST**`/api/v1/assignments`

```json
{
  "contractor": "cn_123",
  "job": "jb_ABC123",
  "coverage_type": ["workers-comp"],
  "effective_date": 1701561600,
  "end_date": 1701907200
}
```

**Note**: If the contractor has a completed general opt-in application, the system automatically:

- Checks for existing matching coverage (reuses if found - like [repeat coverage](/content/docs/repeat-coverage/index.html))
- Binds new coverage using the pre-completed application (if no matching coverage exists)
- Associates the assignment with the coverage

**Important**: If matching coverage already exists (e.g., from a previous assignment with the same job category and work state), that coverage is reused - no new policy binding needed.