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

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

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

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:

{
  "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

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

{
  "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

{
  "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)
• 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.