Getting started

Everything you need to know to start using 1099Policy.

If you have questions as you begin integrating with 1099Policy, you can always email us at integration@1099policy.com.

Introduction

The goal of this guide is to help you quickly integrate with the 1099Policy API while familiarizing you with the concepts central to understanding how our API works. By the end of this guide, you'll be able to integrate our API and give independent contractors on your platform access to workers comp and liability insurance coverage, on-demand.

We have example apps written in Node and Python (Java and Ruby coming soon) available at our Github repository. You can follow the repo README instructions to run the example app locally. As you experiment with the app functionality locally, refer back to this step-by-step guide to better understand the different parts of the app. Alternatively, you can read through this guide first before testing out the app locally.

For additional details, you can refer to our API documentation.

Product Definitions

Below are some helpful definitions you need to know before you get started.

API Key

There are two keys you'll use to authenticate with the 1099Policy API.

Both can be found in the API Keys page of your dashboard. Note that the secret key is specific to the API environment (e.g., sandbox, production) which you can learn more about below.

API Environments

Use our sandbox environment to build out and test your integration with simulated contractors. Once you’re ready to go live, you’ll move to our Production environment.

Core Resources

In broad terms, 1099Policy needs to collect enough information to know:

1. Details about the contractor that’s doing the work (e.g., contractor endpoint)
2. The ultimate client that the contractor is doing the work for, i.e., Nike etc (e.g., entity endpoint)
3. The type of work that the creator is being asked to do and remuneration, i.e., Instagram post for $5,000 (e.g., job endpoint); and
4. The type of coverage that the creators needs (e.g., workers-comp and general liability) and the duration of the engagement (e.g., quote endpoint).

That’s the extent of it! The examples below provide example requests that you can refrence when setting up your integration.

Create an independent contractor

The contractor object is a key building block to every policy we bind and represents the real life independent contractor on your platform. The contractor object is persisted, so you can use the same contractor ID to secure insurance coverage in the future.

Let's start by creating a test contractor object. Remember to replace the secret key below with your test secret key.

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.1099policy.com/keys
ten99policy.api_key = "t9k_test_4eC39HqLyjWDarjtT1zdp7dc"

contractor = ten99policy.Contractors.create(
    first_name="Contractor",
    last_name="Name",
    email="contractor.name@gmail.com",
    phone="51231203",
    address={
        "line1": "1 Kearny",
        "locality": "San Francisco",
        "region": "CA",
        "postalcode": 94104
    }
)

Take note of the contractor id that gets returned since it's used along with the job id to quote and bind coverage. Note that all personally identifiable information is encrypted in transit and at rest.

Record the entity

The entity object is used to store the name and requirements of the contracting entity that the contractor is doing work for. The request below illustrates how you'd go about creating an entity object.

entity = ten99policy.Entities.create(
    name="Lake View Bowl",
    coverage_limit={
      "aggregate_limit": "200000000",
      "occurrence_limit": "100000000"
    },
    address={
      "line1": "3639 18th St",
      "line2": "",
      "locality": "Chicago",
      "region": "IL",
      "postalcode": "60640"
    },
    required_coverage=[
      "general",
      "workers-comp"
    ]
)

In the response, you'll receive an id which you'll use when creating the job object.

Define the job

The job object is used to store the description of the work that the contractor is doing, remuneration, and the contract duration for the role to be filled by the independent contractor. You can see a list of the 600+ job classifications eligible for coverage via the 1099Policy API on our job classification page.

job = ten99policy.Jobs.create(
    name="Field technician",
    description="Run cable from front of commercial building to rear.",
    duration_hours=20,
    wage=12000,
    years_experience=20,
    wage_type="flatfee",
    entity_id="en_FwZfQRe4aW",
    category_code="jc_MTqpkbkp6G"
)

In the response, you'll receive an id which you'll use together with a contractor id to request an insurance quote as described in further detail below.

Retrieve a quote

Once you have both the job and the contractor objects created, you're ready to request an insurance quote by creating a quote object. You'll need to specify the coverage type to request a quote (e.g., workers-comp, general, etc.). You can find the complete list of available coverage types in our full reference API documentation

resource = ten99policy.InsuranceApplicationSessions.create(
    quote="qt_yVEnbNaWh6",
    success_url="http://example.com/success",
    cancel_url="http://example.com/cancel"
)

The quote response includes details useful to the contractor in deciding whether the coverage is right for them, including net_rate, and eligibility, e.g., eligible.

#Quote response
{
	"id": "qt_4M7sjSqdam",
	"job": "jb_jsb9KEcTpc",
	"contractor": "cn_yJBbMeq9QA",
	"coverage_type": [
		"workers-comp",
		"general"
	],
	"quote_json": {
    'wc': {
      'state': 'IL',
      'wc_code': 8810,
      'net_rate': 27
    },
    'gl': {
      'state': 'IL',
      'gl_code': 41677,
      'net_rate': 17,
      'residence_state': 'IL',
      'tax_rate': '0.03500',
      'stamping_fee_rate': '0.00040'
    }
  },
	"net_rate": 44,
	"eligible": true,
	"effective_date": 1701561600,
	"end_date": 1701907200,
	"created": 1699309311
}

Create an insurance application session

The final step in the process is creating an insurance application session which returns a unique url that you provide to the contractor to complete their insurance application and secure coverage.

resource = ten99policy.InsuranceApplicationSessions.create(
    quote="qt_4M7sjSqdam",
    success_url="http://example.com/success",
    cancel_url="http://example.com/cancel"
)

The session response includes the URL that you share with the contractor to complete their insurance applicaiton. Here's an example of what's returned after you create a session object.

#Session response
{
	"id": "ias_01GEEQT5WW55R6941N7BABTYGT",
	"success_url": "https://example.com/success",
	"cancel_url": "https://example.com/cancel",
	"url": "https://apply.1099policy.com/ias_01ABCXYZ123456N7LMNOP",
	"quotes": "qt_4M7sjSqdam",
	"policies": "",
	"created": 1664794564
}

Finally, we'll post an event to your registered webhook URL to notify you when the contractor completes their application. You can learn more about setting up your registered webhook URL and the full list of webhook events that we make available under the Automating Insurance Compliance section of our documentation.

Conclusion

Well done! You now know what it takes to provide independent contractors on your platform the insurance coverage they need and that the contracting enterprises require. Explore the additional guides and examples to better understand the setup process and use cases that we support.