# Getting Started

## Overview

The goal of this guide is to help you quickly integrate with the 1099Policy API and get you familiar 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 client libraries 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 client libraries locally. As you experiment with the library 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.

| Term          | Definition                                                                                                                            |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------|
| **public_key** | a non-sensitive, public identifier that you use for acquiring a limited time access_token for connecting with the 1099Policy API.   |
| **secret**     | a private identifier that is paired with client_id and required for fetching quotes and binding coverage.                             |

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

| Term         | Definition                                                                                                               |
|--------------|--------------------------------------------------------------------------------------------------------------------------|
| **sandbox**   | A stateful sandbox environment used for testing credentials and your integration                                        |
| **production**| Production API environment that's required to place insurance coverage with our partner carriers.                        |

Use our `sandbox` environment to build out and test your integration with test 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](https://docs.1099policy.com/group/endpoint-contractor) endpoint)
2. The ultimate client that the contractor is doing the work for, i.e., Nike etc (e.g., [entity](https://docs.1099policy.com/group/endpoint-entity) endpoint)
3. The type of work that the contractor is being asked to do and remuneration, i.e., Instagram post for $5,000 (e.g., [job](https://docs.1099policy.com/group/endpoint-job) endpoint); and
4. The type of coverage that the contractor needs (e.g., workers-comp and general liability) and the duration of the engagement (e.g., [quote](https://docs.1099policy.com/group/endpoint-quote) endpoint).

That’s the extent of it! Figure 1. and the examples below illustrate and detail the requests that you can reference when setting up your integration.

Figure 1. Platform to 1099Policy sequence diagram

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

```python
# 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.

```python
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](/content/docs/work-classification/index.html) page.

```python
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"
)
```

Job category code

During your setup process we'll provide you with a pre-approved list of job category codes specific to your organization that you will use when creating job objects. You'll find the full list of unique code codes under the [/job-codes](https://dashboard.1099policy.com/job-codes) tab of your dashboard.

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](https://docs.1099policy.com/operation/operation-post-api-v1-quotes#operation-post-api-v1-quotes-body-coverage_type)

```python
resource = ten99policy.Quotes.create(
    job="jb_jsb9KEcTpc",
    contractor="cn_yJBbMeq9QA",
    coverage_type=["general", "workers-comp"],
)
```

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

```python
#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.

```python
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.

```python
#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](/content/docs/automating-compliance/index.html) 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.