Overview

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.

For additional details, you can refer to our API documentation. If you have questions, message us at support@1099policy.com.

We have example apps written in Java, Node, Python, and Ruby 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.

Product Definitions

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

API Keys

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

TermDefinition
public_keya non-sensitive, public identifier that you use for acquiring a limited time access_token for connecting with the 1099Policy API.
client_ida private identifier that is paired with the secret and required for fetching quotes and binding coverage.
secreta private identifier that is paired with client_id and required for fetching quotes and binding coverage.

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

API Environments

TermDefinition
sandboxA stateful sandbox environment used for testing credentials and your integration
developmentTest your integration with live credentials and get real coverage quotes you can bind and make test premium payments.
productionProduction API environment that's required to place insurance coverage with our partner carriers.

Use our Sandbox and Development environments to build out and test your integration with simulated and live users, respectively. Once you’re ready to go live, you’ll move to our Production environment.

Define the type of job

The job object is a key building block to every policy we bind. It's used to define the job classification 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.

Let's start by creating a test job 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/account/apikeys
ten99.api_key = "t9k_test_4eC39HqLyjWDarjtT1zdp7dc"

job = ten99policy.Job.create(
  classification=7699,
  description="Seeking experienced front-end engineer with 5+ years experience",
  duration_hours=40,
  hourly_wage=50000
)

In the response, you'll receive an id which you'll use together with a contractor id to request an insurance quote – find additional details below.

Create an independent contractor

The contractor object 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.

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

contractor = ten99policy.Contractor.create(
  first_name="Your",
  middle_name="Full",
  last_name="Name",
  email="your.name@example.com",
  phone=777777777,
  line1="Your street"
  line2="Your suite"
  city="Your town"
  zipcode=90401,
  dob="1970-01-22",
  driver_license_number=F1112001,
  driver_license_state="CA"
)

Take note of the contractor id that gets returned since, as noted above, it's used along with the job id to quote and bind coverage.

Retrieve a quote and bind insurance

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. You can find the complete list of available coverage types in our full reference API documentation

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

quote = ten99policy.Quote.create(
  contractor_id="con_4fdAW5ftNQow1a",
  job_id="wrk_6fvAH5ltZQo2oa",
  coverage=["workers-comp", "general-liability"],
)

The quote response includes details useful for helping the contractor make a decision about whether the coverage is right for them, including coverage_daily_rate, and links to the policy, e.g., workers_comp_policy_uri.

#RETRIEVE QUOTE RESPONSE
{
  "id": "quote_CbvZlrtet27kcB",
  "created_at": "2018-12-14T17:45:34Z",
  "contractor_id":"con_4fdAW5ftNQow1a",
  "job_id":"wrk_6fvAH5ltZQo2oa",
  "coverage_daily_rate": 10000,
  "workers_comp_policy_uri": "/v1/policy/wc/quote_CbvZlrtet27kcB",
  "general_liability_policy_uri": "/v1/policy/gl/quote_CbvZlrtet27kcB",
  "wrokers_comp_policy_expiry":"2019-12-14T17:45:34Z",
  "general_liability_policy_expiry":"2019-12-14T17:45:34Z",
}

The final step in the process is binding coverage which returns a policy_number in the response along with additional coverage details.

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

job_type = ten99policy.Bind.create(
  quote_id="quote_CbvZlrtet27kcB",
)
#RETRIEVE BOUND POLICY RESPONSE
{
  "id": "policy_CbvZlrtet27kcB",
  "created_at": "2018-12-14T17:45:34Z",
  "contractor_id":"con_4fdAW5ftNQow1a",
  "job_id":"wrk_6fvAH5ltZQo2oa",
  "workers_comp_certificate_uri": "/v1/policy/wc/quote_CbvZlrtet27kcB",
  "general_liability_certificate_uri": "/v1/policy/gl/quote_CbvZlrtet27kcB",
  "wrokers_comp_policy_expiry":"2019-02-14T17:45:34Z",
  "general_liability_policy_expiry":"2018-02-14T17:45:34Z",
}

Note that the response includes links to the certificate of insurance ACORD forms which can be persisted and used to prove coverage as needed.

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