```json { "basePath": "/api", "components": { "examples": { "address": { "line1": "1 Kearny St", "locality": "San Francisco", "postalcode": 94114, "region": "CA" }, "assignment": { "contractor": "cn_Ehb3bYa", "effective_date": 1646818364, "end_date": 1678334737, "job": "jb_jsb9KEcTpc", "policy": "pl_WzFRszJhoY" }, "assignments": [ { "bind": true, "certificates": { "gl_coi_pdf_url": "/bound-policies/prod/gl_coi_pl_wv23Q3lMc1_1691450123.pdf", "wc_coi_pdf_url": "/bound-policies/prod/wc_coi_pl_wv23Q3lMc1_1691420903.pdf" }, "contractor": "cn_Ehb3bYa", "created": 1646818364, "effective_date": 1646818364, "eligible": { "message": "Contractor is pre-approved for insurance coverage.,", "result": true }, "end_date": 1678334737, "id": "an_TzLQszJmoP", "job": "jb_jsb9KEcTpc", "policy": "pl_WzFRszJhoY" } ], "cancelled_assignment": { "cancellation_date": 1678334737, "cancellation_reason": "client_request", "cancelled": true, "certificates": null, "contractor": "cn_Ehb3bYa", "coverage_type": [ "general", "workers-comp" ], "effective_date": 1646818364, "eligible": { "message": "Contractor is pre-approved for insurance coverage.", "result": true }, "end_date": 1678334737, "id": "an_5HviNgc2Br", "job": "jb_jsb9KEcTpc", "net_rate": 65, "policy": "pl_WzFRszJhoY" }, "category_codes": [ { "category_code": "jc_MTqpkbkp6G", "name": "Computer Service or Repair" }, { "category_code": "jc_5Tqpkbkp6G", "name": "Spokesperson / Influencer" } ], "certificate": { "contractor": "cn_Ehb3bYa", "created": 1646818364, "filename": "certificate_of_insurance.pdf", "id": "ci_abc123", "pdf_url": null, "review_results": null, "status": "pending", "updated": 1646818364 }, "certificate_approved": { "contractor": "cn_abc123", "created": 1646818000, "filename": "coi_2024.pdf", "id": "ci_def456", "pdf_url": "https://storage.example.com/certificates/ci_def456.pdf", "review_results": { "created": 1646818500, "id": "ca_audit789", "status": "approved", "summary": { "failed": 0, "passed": 5, "total_rules": 5 } }, "status": "approved", "updated": 1646818500 }, "certificate_with_expanded_results": { "contractor": "cn_Ehb3bYa", "created": 1646818000, "filename": "coi_2024.pdf", "id": "ci_def456", "pdf_url": "https://storage.example.com/certificates/ci_def456.pdf", "review_results": { "audit_results": [ { "created": 1646818500, "id": "car_result1", "manually_approved": false, "message": "General aggregate limit meets requirement of $2,000,000", "result": "pass", "rule_name": "CGL General Aggregate Limit", "rule_path": "coverages.commercial_general_liability.limits.general_aggregate_dollars" }, { "created": 1646818500, "id": "car_result2", "manually_approved": false, "message": "Occurrence limit meets requirement of $1,000,000", "result": "pass", "rule_name": "CGL Occurrence Limit", "rule_path": "coverages.commercial_general_liability.limits.occurrence_limit_dollars" } ], "created": 1646818500, "id": "ca_audit789", "parsed_certificate_json": { "certificate_holder": { "name": "Acme Corporation" }, "coverages": { "commercial_general_liability": { "limits": { "general_aggregate_dollars": 2000000, "occurrence_limit_dollars": 1000000 } } }, "date": "01/01/2024" }, "status": "approved", "updated": 1646818500 }, "status": "approved", "updated": 1646818500 }, "certificates": [ { "contractor": "cn_xyz789", "created": 1646818364, "filename": "certificate_of_insurance.pdf", "id": "ci_abc123", "pdf_url": null, "review_results": null, "status": "pending", "updated": 1646818364 }, { "contractor": "cn_Ehb3bYa", "created": 1646818000, "filename": "coi_2024.pdf", "id": "ci_def456", "pdf_url": "https://storage.example.com/certificates/ci_def456.pdf", "review_results": { "created": 1646818500, "id": "ca_audit789", "status": "approved", "summary": { "failed": 0, "passed": 5, "total_rules": 5 } }, "status": "approved", "updated": 1646818500 } ], "contractor": { "address": { "line1": "1 Kearny St", "locality": "San Francisco", "postalcode": 94104, "region": "CA" }, "company_name": "Acme Co.", "custom_metadata": { "campaign": "Red Bull" }, "email": "parker@gmail.com", "first_name": "Joe", "last_name": "Parker", "phone": "415-474-9088", "tax_identification": "12-3456789" }, "contractor_policies": [ { "certificates": { "gl_coi_pdf_url": "/bound-policies/prod/gl_coi_pl_wv23Q3lMc1_1691450123.pdf", "wc_coi_pdf_url": "/bound-policies/prod/wc_coi_pl_wv23Q3lMc1_1691420903.pdf" }, "created": 1646818364, "effective_date": 1646818364, "expiration_date": 1678334737, "id": "pl_WzFRszJhoY", "pdf_url": "http://ten99policy.s3.amazonaws.com/1099policy-coi-sample.pdf", "quote": { "coverage_type": [ "general", "workers-comp" ], "id": "qt_5DciVga8Kt", "quote_json": {} }, "status": "active" } ], "contractors": [ { "address": { "line1": "150 Wythe Ave", "locality": "Brooklyn", "postalcode": 11249, "region": "NY" }, "company_name": "Mass Repair", "created": 1646818364, "custom_metadata": { "campaign": "Volvo" }, "email": "fmoss@gmail.com", "first_name": "Fredrick", "id": "cn_Zbe1qTc", "last_name": "Moss", "phone": "916-579-1243", "withhold_premium": false }, { "address": { "line1": "1 Kearny St", "locality": "San Francisco", "postalcode": 94104, "region": "CA" }, "company_name": "Acme Co.", "created": 1646818384, "custom_metadata": { "campaign": "Red Bull" }, "email": "parker@gmail.com", "first_name": "Joe", "id": "cn_Ehb3bYa", "last_name": "Parker", "phone": "415-474-9088", "withhold_premium": false } ], "coverage_limit": { "aggregate_limit": 200000000, "occurrence_limit": 100000000 }, "entities": [ { "address": { "line1": "One Apple Park Way", "locality": "Cupertino", "postalcode": 95014, "region": "CA" }, "coverage_limit": { "aggregate_limit": 200000000, "occurrence_limit": 100000000 }, "created": 1646818364, "id": "en_Ah3tqYn", "name": "Apple, Inc", "required_coverage": [ "general", "workers-comp" ] }, { "address": { "line1": "410 Terry Ave N", "locality": "Seattle", "postalcode": 98109, "region": "WA" }, "coverage_limit": { "aggregate_limit": 500000000, "occurrence_limit": 100000000 }, "created": 1646818386, "id": "en_Mg5sqSp", "name": "Amazon, Inc", "required_coverage": [ "general", "professional" ] } ], "entity": { "address": { "line1": "One Apple Park Way", "locality": "Cupertino", "postalcode": 95014, "region": "CA" }, "coverage_limit": { "aggregate_limit": 200000000, "occurrence_limit": 100000000 }, "name": "Apple, Inc", "required_coverage": [ "general", "workers-comp" ] }, "event": { "data": { "created": 1646818364, "effective_date": 1646818364, "expiration_date": 1678334737, "id": "pl_WzFRszJhoY", "object": "policy", "pdf_url": "http://ten99policy.s3.amazonaws.com/1099policy-coi-sample.pdf", "quote": "qt_5DciVga8Kt", "status": "active" }, "type": "policy.active" }, "events": [ { "created": 1646818364, "data": { "created": 1646818364, "effective_date": 1646818364, "expiration_date": 1678334737, "id": "pl_WzFRszJhoY", "object": "policy", "pdf_url": "http://ten99policy.s3.amazonaws.com/1099policy-coi-sample.pdf", "quote": "qt_5DciVga8Kt", "status": "active" }, "id": "ev_Q2kA9Nsub9jKcFJqcBSv2u", "type": "policy.active" } ], "expired_session": { "cancel_url": "https://1099jobcloud.com/1099policy/cancel", "expired": true, "quote": "qt_5DciVga8Kt", "success_url": "https://1099jobcloud.com/1099policy/success" }, "invoice": { "contractor": "cn_Ehb3bYa", "gross_pay": 250000, "job": "jb_jsb9KEcTpc", "paycycle_enddate": 1678334737, "paycycle_startdate": 1646818364 }, "job": { "category_code": "jc_MTqpkbkp6G", "custom_metadata": { "campaign": "Volvo" }, "description": "Install fiber optic cable from back to the front of the store.", "entity": "en_Ah3tqYn", "name": "Field technician", "wage": 15000, "wage_type": "flatfee", "years_experience": 10 }, "jobs": [ { "category_code": "jc_MTqpkbkp6G", "created": 1646818364, "custom_metadata": { "campaign": "Volvo" }, "description": "BMW engine diagnostics and troubleshooting.", "entity": "en_C9Z2DmfHSF", "id": "jb_jsb9KEcTpc", "name": "Mechanic technician", "wage": 1500, "wage_type": "flatfee", "years_experience": 5 } ], "policies": [ { "certificates": { "gl_coi_pdf_url": "/bound-policies/prod/gl_coi_pl_wv23Q3lMc1_1691450123.pdf", "wc_coi_pdf_url": "/bound-policies/prod/wc_coi_pl_wv23Q3lMc1_1691420903.pdf" }, "created": 1646818364, "effective_date": 1646818364, "expiration_date": 1678334737, "id": "pl_WzFRszJhoY", "pdf_url": "http://ten99policy.s3.amazonaws.com/1099policy-coi-sample.pdf", "quote": "qt_5DciVga8Kt", "status": "active" } ], "policy": { "effective_date": 1646818364, "expiration_date": 1678334737, "quote": "qt_5DciVga8Kt" }, "quote": { "contractor": "cn_Ehb3bYa", "coverage_type": [ "general", "workers-comp" ], "job": "jb_jsb9KEcTpc" }, "quotes": [ { "contractor": "cn_Ehb3bYa", "coverage_type": [ "general", "workers-comp" ], "created": 1646818364, "eligible": true, "gl_net_rate": 20, "id": "qt_5DciVga8Kt", "job": "jb_jsb9KEcTpc", "net_rate": 65, "quote_json": { "gl": { "net_rate": 20, "risk_purchasing_group_fee": null, "stamping_fee": null }, "wc": { "net_rate": 45 } }, "wc_net_rate": 45 } ], "session": { "cancel_url": "https://1099jobcloud.com/1099policy/cancel", "quote": "qt_5DciVga8Kt", "success_url": "https://1099jobcloud.com/1099policy/success" }, "sessions": [ { "cancel_url": "https://1099jobcloud.com/1099policy/cancel", "created": 1646818364, "expired": false, "id": "ias_01FZCHXE7KNQHE1T3S8AXG2QZE", "quote": "qt_5DciVga8Kt", "step": "final_review", "success_url": "https://1099jobcloud.com/1099policy/success", "url": "http://apply.1099policy.com?..." } ], "webhook": { "created": 1646818364, "description": "Webhook for contractor insurance application events.", "id": "whe_KPGc5vEZdvoETu39BNwu2Z", "url": "https://example.com/my/webhook/endpoint" }, "webhook_endpoint": { "description": "Webhook for contractor insurance application events.", "url": "https://example.com/my/webhook/endpoint" }, "webhook_endpoints": [ { "created": 1646818364, "description": "Webhook for contractor insurance application events.", "id": "whe_KPGc5vEZdvoETu39BNwu2Z", "url": "https://example.com/my/webhook/endpoint" } ], "webhooks": [ { "created": 1646818364, "description": "Webhook for contractor insurance application events.", "id": "whe_KPGc5vEZdvoETu39BNwu2Z", "url": "https://example.com/my/webhook/endpoint" } ] }, "schemas": { "Address": { "properties": { "country": { "description": "2-letter country code.", "example": "null", "format": null, "nullable": true, "type": "string" }, "line1": { "description": "Address line 1 (Street address/PO Box).", "example": "92 Geary St", "type": "string" }, "line2": { "description": "Address line 2 (Apartment/Suite/Unit/Building).", "example": "null", "format": null, "nullable": true, "type": "string" }, "locality": { "description": "City/District/Suburb/Town/Village.", "example": "San Francisco", "type": "string" }, "postalcode": { "description": "ZIP or postal code.", "example": 94114, "type": "string" }, "region": { "description": "2-letter state code.", "example": "CA", "type": "string" } }, "type": "object" }, "Assignment": { "description": "To secure coverage for independent contractors that have previously had a policy issued through the 1099Policy platform, you create an `Assignment` object. \n\nIndependent contractors with an existing insurance policy procured using the 1099Policy platform have the option to receive per-job-assignment insurance coverage without having to complete additional insurance applications, provided certain eligibility criteria are met. \n\nYou can find the result of the eligibility check in the API response. Eligiblity is determined by parameters provided, including `job` and `contractor`. In particular, we look to see if the job `category_code` is the same as previously approved and the time since the independent contractor completed their insurance application.\n\n1099Policy automatically charges the independent contractor's credit card on file, if a credit card exists and `bind` is `true`. 1099Policy first notifies the contractor via email and then charges the contractor the premium amount due 24hrs later.", "properties": { "bind": { "default": true, "description": "Indicates whether to start the process of binding coverage, which includes notifying and subsequently charging the independent contractor for the premium amount due. Defaults to `true`. When false, 1099Policy does not notify or schedule a charge. Note that the independent contractor will not be issued coverage if bind is set to `false`." }, "certificates": { "allOf": [ { "$ref": "#/components/schemas/CertificateUrls" }, { "type": "object" } ] }, "contractor": { "description": "ID of the contractor.", "example": "cn_Ehb3bYa", "type": "string" }, "coverage_type": { "description": "An array of coverage types that can include one or more of the following insurance coverage values: `general`, `professional` and `workers-comp`. If provided, coverage type is factored into the eligibility determination (i.e., does contractor have an active `workers-comp` policy, etc). Defaults to the coverage types of the most recent active policy if `coverage_type` is not provided.", "example": [ "general", "workers-comp" ], "items": { "enum": [ "general", "professional", "workers-comp" ], "type": "string" }, "type": "array" }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "effective_date": { "description": "The job assignment start date, measured in seconds since the Unix epoch.", "example": 1646818364, "format": "int64", "type": "integer" }, "eligible": { "allOf": [ { "$ref": "#/components/schemas/Eligible" }, { "description": "Indicates whether a contractor is elgible for pre-approved insurance or not based on their most recent insurance application.", "type": "object" } ] }, "end_date": { "description": "The projected job assignment end date, measured in seconds since the Unix epoch.", "example": 1678334737, "format": "int64", "type": "integer" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "an_5HviNgc2Br" }, "job": { "description": "ID of the job that the contractor intends to accept.", "example": "jb_jsb9KEcTpc", "type": "string" }, "net_rate": { "description": "The amount of money the 1099 contractor pays in premium per every $100 earned.\n\nA positive integer representing the premium owed per $100 earned. The `net_rate` is stored in cents (e.g., 48 represents $0.48).", "example": 65, "readOnly": true, "type": "integer" }, "policy": { "description": "ID of the policy that you want attached to the assignment. Defaults to the most recent active policy with a matching job category code, work state and contractor home state.", "example": "pl_WzFRszJhoY", "type": "string" } }, "type": "object" }, "CategoryCodes": { "description": "The job category code object represents the pre-approved job category name and unique code that you receive when you onboard onto 1099Policy. Use this read-only endpoint to get your full list of the job category names and codes that your organization is pre-approved to use.", "properties": { "category_code": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "jc_MTqpkbkp6G" }, "name": { "description": "The name of the job category code.", "example": "Spokesperson / Influencer", "type": "string" } }, "type": "object" }, "Certificate": { "description": "A Certificate object represents a Certificate of Insurance (COI) document that a contractor has provided. The certificate is processed asynchronously to evaluate it against your organization's insurance requirements.", "properties": { "contractor": { "description": "The ID of the contractor associated with this certificate.", "example": "cn_xyz789", "type": "string" }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ], "description": "Time at which the certificate was uploaded." }, "filename": { "description": "The original filename of the uploaded PDF.", "example": "certificate_of_insurance.pdf", "type": "string" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "description": "Unique identifier for the certificate.", "example": "ci_abc123" }, "pdf_url": { "description": "URL to access the certificate PDF. This will be `null` until the certificate has been processed and stored.", "example": "https://storage.example.com/certificates/ci_abc123.pdf", "nullable": true, "type": "string" }, "review_results": { "description": "Review results from the certificate evaluation. This will be `null` until processing completes. Use `expand[]=review_results` to include abbreviated results, or `expand[]=review_results.full` for complete details.", "nullable": true, "properties": { "audit_results": { "description": "Detailed results for each insurance requirement evaluation (expanded format only).", "items": { "properties": { "created": { "description": "Timestamp when this result was created.", "type": "integer" }, "id": { "example": "car_result123", "type": "string" }, "manually_approved": { "description": "Whether this result was manually approved.", "type": "boolean" }, "message": { "description": "Human-readable message about the evaluation result.", "type": "string" }, "result": { "description": "Whether this requirement passed or failed.", "enum": [ "pass", "fail" ], "type": "string" }, "rule_name": { "description": "Human-readable name of the rule.", "example": "CGL Limits", "type": "string" }, "rule_path": { "description": "The path to the rule being evaluated.", "example": "coverages.commercial_general_liability.limits", "type": "string" } }, "type": "object" }, "type": "array" }, "created": { "description": "Timestamp when the audit was created.", "type": "integer" }, "id": { "description": "The ID of the certificate audit.", "example": "ca_audit123", "type": "string" }, "parsed_certificate_json": { "description": "Full parsed certificate data extracted from the PDF (expanded format only). Contains structured data including coverages, limits, dates, and parties.", "type": "object" }, "status": { "description": "The final evaluation status.", "enum": [ "pending", "processing", "approved", "flagged", "denied", "error" ], "type": "string" }, "summary": { "description": "Summary of rule evaluation (abbreviated format only).", "properties": { "failed": { "description": "Number of requirements that failed.", "example": 0, "type": "integer" }, "passed": { "description": "Number of requirements that passed.", "example": 5, "type": "integer" }, "total_rules": { "description": "Total number of insurance requirements evaluated.", "example": 5, "type": "integer" } }, "type": "object" }, "updated": { "description": "Timestamp when the audit was last updated.", "type": "integer" } }, "type": "object" }, "status": { "description": "The current processing status of the certificate. Status transitions: `pending` → `processing` → (`approved` | `flagged` | `denied` | `error`). Use polling or webhooks to monitor status changes.", "enum": [ "pending", "processing", "approved", "flagged", "denied", "error" ], "example": "pending", "type": "string" }, "updated": { "allOf": [ { "$ref": "#/components/schemas/Created" } ], "description": "Time at which the certificate was last updated." } }, "type": "object" }, "CertificateUrls": { "description": "URLs to the certificates of insurance for each of the types of coverage issued to the contractor for the specific job assignment.", "properties": { "gl_coi_pdf_url": { "description": "The general liability certificate of insurance PDF URL.", "example": "/bound-policies/prod/gl_coi_pl_wv23Q3lMc1_1691450123.pdf", "type": "string" }, "wc_coi_pdf_url": { "description": "The workers compensation certificate of insurance PDF URL.", "example": "/bound-policies/prod/wc_coi_pl_wv23Q3lMc1_1691420903.pdf", "type": "string" } }, "readOnly": true, "type": "object" }, "Contractor": { "description": "A `Contractor` object represents the contractors that can accept one or more jobs on your platform. The API allows you to create, delete, and update contractors. You can retrieve individual contractors as well as a list of all contractors.", "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "description": "The contractor's home address.", "type": "object" } ] }, "company_name": { "description": "The contractor's business name.", "example": "Acme Co.", "nullable": true, "type": "string" }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "custom_metadata": { "description": "Set of key-value pairs that you can attach to the contractor object. Used for storing additional information in a structured format. Individual keys can be unset by posting an empty value to them. Pass an empty value, e.g. {}, to custom_metadata to unset all keys.", "example": { "campaign": "Red Bull" }, "type": "object" }, "email": { "description": "The contractor's email address.", "example": "parker@gmail.com", "type": "string" }, "first_name": { "description": "The contractor's first name.", "example": "Joe", "type": "string" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "cn_Ehb3bYa" }, "last_name": { "description": "The contractor's last name.", "example": "Parker", "type": "string" }, "middle_name": { "description": "The contractor's middle name.", "example": "null", "format": null, "nullable": true, "type": "string" }, "phone": { "description": "The contractor's phone number.", "example": "415-474-9088", "type": "string" }, "withhold_premium": { "default": false, "description": "This indicates whether the contractor is paying premium directly with their credit card (i.e., `false`) or if the contractor has given the platform that's integrating with 1099Policy permission to withhold the premium payment from their wages and pay the premium on the contractor's behalf (i.e., `true`). Defaults to `false`. " } }, "type": "object" }, "Coverage": { "description": "An array of coverage types that can include one or more of the following insurance coverage values: `general`, `professional`, `workers-comp`, `media`, and `cyber`.", "example": [ "general", "workers-comp" ], "items": { "enum": [ "general", "professional", "workers-comp", "media", "cyber" ], "type": "string" }, "type": "array" }, "Created": { "description": "Time at which the object was created. Measured in seconds since the Unix epoch.", "example": 1646818364, "format": "int64", "readOnly": true, "type": "integer" }, "Eligible": { "description": "Object with the result of the insurance eligiblity check for a given job assignment.", "properties": { "message": { "description": "A message with more detail related to the eligibility result.", "example": "Contractor is pre-approved for insurance coverage.", "type": "string" }, "result": { "description": "The result of the insurance eligibility check.", "example": true, "type": "boolean" } }, "type": "object" }, "Entity": { "description": "The `Entity` object represents the contracting entity responsible for defining the job descriptions and for hiring contractors.\n\nThe API allows you to create, delete, and update entities. You can retrieve individual entities as well as a list of all entities.", "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "description": "The contracting entity's address.", "type": "object" } ] }, "coverage_limit": { "allOf": [ { "$ref": "#/components/schemas/Limit" } ], "description": "The contracting entity's minimum required coverage limits." }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "en_Ah3tqYn" }, "name": { "description": "The contracting entity's legal name.", "example": "Apple, Inc", "type": "string" }, "required_coverage": { "description": "An array of coverage types that can include one or more of the following insurance coverage values: `general`, `professional` and `workers-comp`.", "example": [ "general", "workers-comp" ], "items": { "enum": [ "general", "professional", "workers-comp" ], "type": "string" }, "type": "array" } }, "type": "object" }, "Event": { "description": "Events are how we communicate notable activity on an independent contractor's insurance application and policy. When an event occurs, we create a new `Event` object. For example, when an insurance application is started, we create an `application.started` event; and when a policy is issued, we create a `policy.active` event.\n\nAPI resource state changes trigger events. The state of that resource at the time of the change is embedded in the event's data field. For example, an `application.started` event will contain an insurance application `Session` object, and a `policy.active` event will contain a `Policy` object.\n\nUse the events endpoints to retrieve an individual event or a list of events. You can listen for events by registering your server endpoint via the 1099Policy [dashboard](https://dashboard.1099policy.com/webhooks). Our webhooks system send the Event objects directly to your registered endpoint.", "properties": { "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/Object" }, { "description": "Object containing data associated with the event.", "type": "object" } ] }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "ev_1a2b3c4d5e6f" }, "type": { "description": "Description of the event (e.g., application.started, policy.active, certificate.approved, certificate.flagged, certificate.denied).", "example": "policy.cancelled", "type": "string" } }, "type": "object" }, "Id": { "description": "Unique identifier for the object.", "readOnly": true, "type": "string" }, "Invoice": { "description": "Invoices are statements of premium amounts owed by a contractor, based on the contractor's gross pay in the last pay period.\n\nThe invoice is used by 1099Policy to determine total amount to charge the contractor's credit card or relay to the gig-platform the premium owed by the contractor to the 1099Policy platform.", "properties": { "contractor": { "description": "ID of the contractor.", "example": "cn_Ehb3bYa", "type": "string" }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "gross_pay": { "description": "The gross pay that the contractor earned in the last pay period.\n\nA positive integer representing the gross pay (e.g., 15000 cents to charge $150.00). The minimum amount is 100 cents US. The maximum amount is 100000000 cents US ($1,000,000).", "example": 250000, "maximum": 100000000, "minimum": 100, "type": "integer" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "in_4RviYgc2Wt" }, "job": { "description": "ID of the job that the contractor was paid to do.", "example": "jb_jsb9KEcTpc", "type": "string" }, "paycycle_enddate": { "description": "Pay period end date. Measured in seconds since the Unix epoch.", "example": 1678334737, "format": "int64", "type": "integer" }, "paycycle_startdate": { "description": "Pay period start date. Measured in seconds since the Unix epoch.", "example": 1646818364, "format": "int64", "type": "integer" }, "premium_due": { "description": "Premium due for pay cycle. Calculated as a percentage of gross pay for the period.\n\nA positive integer representing the premium due (e.g., 150 cents to charge $1.50). The minimum amount is 100 cents US.", "example": 4325, "readOnly": true, "type": "integer" }, "purchase_order_number": { "description": "The purchase order number for this invoice. Used for dashboard display and agency-pay billing.\n\nBy default an invoice inherits this from the `purchase_order_number` set on the job's `custom_metadata` when it is created. It can be overridden per invoice on create or update by sending `purchase_order_number` (an explicit value wins over the job default), or cleared by sending an empty string (`\"\"`). Omitting the field on update leaves the current value unchanged.\n\nWhen a wage change re-prices an invoice, the replacement invoice keeps this value rather than re-inheriting it from the job.\n\nPrecedence: explicit value on the invoice, then the value carried forward when an invoice is re-priced, then the job's `custom_metadata` default.", "example": "12345678", "type": "string" } }, "type": "object" }, "Job": { "description": "Store representations of the jobs on your platform in `Job` objects. The `Job` is used to, among other things, ensure that the insurance coverage that the 1099Policy platform issues correctly maps to the work that contractors will do.", "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "description": "The job address where the work will be done. Exclude if job will be done remotely.", "type": "object" } ] }, "category_code": { "description": "The category code that 1099Policy creates for a group of similarly classified jobs.\n\nJob category codes are pre-approved by 1099Policy so you can offer contractors insurance to new jobs on your platform in real time.\n\nTo generate pre-approved category codes for a group of similarly classified jobs visit the [1099Policy Dashboard](https://dashboard.1099policy.com/jobs).", "example": "jc_MTqpkbkp6G", "type": "string" }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "custom_metadata": { "description": "Set of key-value pairs that you can attach to the job object. Used for storing additional information in a structured format. Individual keys can be unset by posting an empty value to them. Pass an empty value, e.g. {}, to custom_metadata to unset all keys.\nThe `purchase_order_number` key is recognized: invoices created for this job inherit it as their purchase order number (overridable or clearable per invoice via the invoice endpoints).", "example": { "campaign": "Red Bull" }, "type": "object" }, "description": { "description": "A description of the job that includes the role, responsibilities and necessary qualifications.", "example": "Install fiber optic cable from back to the front of the store.", "type": "string" }, "entity": { "description": "The entity ID for whom the work is being done.", "example": "en_Ah3tqYn", "type": "string" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "jb_jsb9KEcTpc" }, "name": { "description": "The name of the contractor job role.", "example": "Field technician", "type": "string" }, "wage": { "description": "A positive integer representing the total wage (e.g., 1500 cents is $15.00). The minimum wage amount is 100 cents US. The maximum wage amount is 100000000 cents US ($1,000,000).", "example": 15000, "maximum": 100000000, "minimum": 100, "type": "integer" }, "wage_type": { "description": "One of `flatfee`, `hourly`, `unit` or `blended`.", "enum": [ "flatfee", "hourly", "unit", "blended" ], "example": "flatfee" }, "years_experience": { "description": "The number of years of experience required to be eligible for the job.", "example": 10, "type": "integer" } }, "type": "object" }, "Limit": { "properties": { "aggregate_limit": { "description": "The total amount the insurance company will pay for multiple claims over the course of one policy term.\n\nA positive integer representing the aggregate limit expressed in cents (e.g., 100000000 cents to represent $1,000,000). The minimum amount is 1000 cents US.", "example": 200000000, "type": "integer" }, "occurrence_limit": { "description": "The total amount the insurance company will pay per incident during the policy term.\n\nA positive integer representing the per occurrence limit expressed in cents (e.g., 100000000 cents to represent $1,000,000). The minimum amount is 1000 cents US.", "example": 100000000, "type": "integer" } }, "required": [ "aggregate_limit", "occurrence_limit" ], "type": "object" }, "MediaCoverage": { "description": "A MediaCoverage object represents a media liability coverage period that tracks published content and ensures coverage is maintained for the required period.", "properties": { "coverage_end_date": { "description": "The date and time when the coverage period ends, measured in seconds since the Unix epoch.", "example": 1678334737, "format": "int64", "type": "integer" }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ], "description": "Time at which the media coverage record was created." }, "first_publication_date": { "description": "The date and time when the first content was published, measured in seconds since the Unix epoch.", "example": 1646818364, "format": "int64", "type": "integer" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "description": "Unique identifier for the media coverage record.", "example": "mc_abc123xyz" }, "is_active": { "description": "Whether the media coverage period is currently active.", "example": true, "type": "boolean" }, "published_content_json": { "description": "Array of published content items. Each item contains publication_date and platform-specific content data.", "example": [], "items": { "type": "object" }, "type": "array" }, "quote_id": { "description": "The ID of the quote associated with this media coverage.", "example": "qt_5DciVga8Kt", "type": "string" } }, "type": "object" }, "Object": { "description": "Object containing the API resource relevant to the event. For example, an `policy.active` event will have a full policy object as the value of the object key.", "readOnly": true, "type": "object" }, "Pagination": { "description": "Pagination is currently available for the list `events` API, and takes the `page` query parameter.", "properties": { "next": { "description": "A cursor for use in pagination. The numeric value used to fetch the next result set.", "example": 0, "type": "integer" }, "page": { "description": "The current page returned in the response.", "example": 1, "type": "integer" }, "perPage": { "description": "The number of results returned per page.", "example": 20, "type": "integer" }, "prev": { "description": "A cursor for use in pagination. The numeric value used to fetch the previous result set.", "example": 0, "type": "integer" }, "total": { "description": "The total number of objects returned by the query.", "example": 3, "type": "integer" }, "totalPage": { "description": "The total number of pages to choose of available paginated results.", "example": 1, "type": "integer" } }, "type": "object" }, "PaymentSession": { "description": "A payment session is a single-use, time-boxed flow that lets one of your contractors add or update a credit card on a secure page hosted by 1099Policy, then return to a URL you control. The session is created on your server, consumed by the contractor's browser via a one-time expiring link, and its outcome is delivered back to your server via a signed webhook.", "properties": { "cancelled_at": { "description": "Time at which the session was cancelled by you or by the contractor. Null unless `status` is `cancelled`. Measured in seconds since the Unix epoch.", "format": "int64", "nullable": true, "readOnly": true, "type": "integer" }, "completed_at": { "description": "Time at which the session reached `completed`. Null unless the contractor successfully saved a card. Measured in seconds since the Unix epoch.", "example": 1713369924, "format": "int64", "nullable": true, "readOnly": true, "type": "integer" }, "contractor_id": { "description": "Public ID of the contractor the session is scoped to.", "example": "cn_Ehb3bYa", "type": "string" }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "expires_at": { "description": "Time at which a pending session expires and becomes unusable. Measured in seconds since the Unix epoch. Default lifetime is 30 minutes from creation.", "example": 1713371724, "format": "int64", "readOnly": true, "type": "integer" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "hps_xyz123abc" }, "processor": { "description": "Identifier for the payment provider backing this session. `checkout` is the default and currently the only supported value. Reserved so future providers can be added without a breaking schema change.", "enum": [ "checkout" ], "example": "checkout", "readOnly": true, "type": "string" }, "return_url": { "description": "HTTPS URL the contractor is redirected to when the flow terminates. The host must be in your organization's configured `hosted_flow_allowed_redirect_hosts` allowlist; exact host match only, no wildcards. URLs with credentials (`user:pass@`) or fragments are rejected at creation time.", "example": "https://app.yourplatform.com/settings/billing/return", "type": "string" }, "status": { "description": "Current status of the session. `pending` is the only state in which the URL can be used; the other three are terminal.", "enum": [ "pending", "completed", "cancelled", "expired" ], "example": "pending", "readOnly": true, "type": "string" }, "url": { "description": "The single-use URL to redirect the contractor to. Shown exactly once, at session creation. The token embedded in this URL is a secret — do not log it, do not persist it, do not share it beyond the contractor's browser.", "example": "https://my.1099policy.com/payment/setup/live_", "readOnly": true, "type": "string" } }, "type": "object" }, "Policy": { "description": "To procure contractor insurance, you create a `Policy` object. You can retrieve individual policies as well as list all policies. Policies are identified by a unique, random ID.\n\nImportant note: Creating a policy via the POST endpoint is an exception for most integrations. A policy object is created automatically when a contractor completes their insurance application (see Session API). Contact us if you plan to use the policy POST endpoint.", "properties": { "certificates": { "allOf": [ { "$ref": "#/components/schemas/CertificateUrls" }, { "type": "object" } ] }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "effective_date": { "description": "A timestamp used to determine the insurance policy start date. Measured in seconds since the Unix epoch. The default effective_date is the next day.", "example": 1646818364, "format": "int64", "type": "integer" }, "expiration_date": { "description": "A timestemp used to determine the insurance policy end date. Measured in seconds since the Unix epoch. The default expiration_date is 30 days after the effective_date.", "example": 1678334737, "format": "int64", "type": "integer" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "pl_WzFRszJhoY" }, "pdf_url": { "description": "A URL for the hosted insurnace policy PDF, which contractors can view.", "example": "http://ten99policy.s3.amazonaws.com/1099policy-coi-sample.pdf", "readOnly": true, "type": "string" }, "quote": { "description": "The ID of the quote used to create the policy.", "example": "qt_5DciVga8Kt", "type": "string" }, "status": { "description": "One of `active`, `cancelled`, or `expired`.", "enum": [ "active", "cancelled", "expired" ], "example": "active", "readOnly": true } }, "type": "object" }, "Quote": { "description": "The `Quote` object reflects whether a contractor is eligible for insurance and the premium owed for every $100 earned.\n\nImportant note: In North Dakota, Ohio, Washington and Wyoming, workers compensation can only be purchased through a government operated insurance company. As a result, the quote API returns an error when a quote request is made for workers compensiation for any one of these four states.", "properties": { "contractor": { "description": "ID of the contractor.", "example": "cn_Ehb3bYa", "type": "string" }, "coverage_type": { "allOf": [ { "$ref": "#/components/schemas/Coverage" } ] }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "effective_date": { "description": "The date when the insurance coverage is set to take effect. Measured in seconds since the Unix epoch. This date must be set in the future. The default effective_date is the next day.", "example": 1646818364, "format": "int64", "type": "string" }, "eligible": { "default": true, "description": "Indicates whether a contractor is elgible for insurance or not.", "readOnly": true, "type": "boolean" }, "end_date": { "description": "The date when the insurance coverage is set to expire. Measured in seconds since the Unix epoch. This date must be after the effective date. The default end_date is 30 days after the effective date.", "example": 1678334737, "format": "int64", "type": "string" }, "gl_net_rate": { "description": "The amount of money the 1099 contractor pays in general liability premium per every $100 earned.\n\nA positive integer representing the premium owed per $100 earned. The `gl_net_rate` is stored in cents (e.g., 48 represents $0.48).", "example": 20, "readOnly": true, "type": "integer" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "qt_5DciVga8Kt" }, "job": { "description": "ID of the job that the contractor was paid to do.", "example": "jb_jsb9KEcTpc", "type": "string" }, "net_rate": { "description": "The amount of money the 1099 contractor pays in premium per every $100 earned.\n\nA positive integer representing the premium owed per $100 earned. The `net_rate` is stored in cents (e.g., 48 represents $0.48).", "example": 65, "readOnly": true, "type": "integer" }, "quote_json": { "description": "The JSON representation of component parts that make up the total premium amount due including, for example, the net rate, taxes, and fees.", "example": { "gl": { "net_rate": 20, "risk_purchasing_group_fee": null, "stamping_fee": null }, "wc": { "net_rate": 45 } }, "readOnly": true, "type": "object" }, "wc_net_rate": { "description": "The amount of money the 1099 contractor pays in workers comp premium per every $100 earned.\n\nA positive integer representing the premium owed per $100 earned. The `wc_net_rate` is stored in cents (e.g., 48 represents $0.48).", "example": 45, "readOnly": true, "type": "integer" } }, "type": "object" }, "Session": { "description": "A Session represents the independent contractor's session as they apply for insurance using the application wizard at apply.1099policy.com. You only need to create a Session for contractors that don't already have insurance coverage.\n\nOnce the contractor successfully completes their insurance application, the Session will contain a reference to the Quote, the Contractor, the Job, and the active insurance Policy.\n\nYou can create a Session on your server and pass its URL to the client to begin the insurance application.", "properties": { "cancel_url": { "description": "The URL the contractor will be directed to if they are ineligible or decide to abandon the insurance application and return to your website.", "example": "https://1099jobcloud.com/1099policy/cancel", "type": "string" }, "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ] }, "expired": { "description": "Indicates whether the insurance application session has expired. If true, the contractor will be redirected to the cancel_url.", "example": false, "type": "boolean" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "ias_01FVCHXE7PNQHA1T3S2AXL2QZE" }, "quote": { "description": "The ID of the quote associated with the insurance application session.", "example": "qt_5DciVga8Kt", "type": "string" }, "step": { "description": "The step in the insurance application process that the contractor is currently on. The contractor will be redirected to this step when they return to the insurance application. One of `verify_info`, `application_questions`, `esignature_document`, `add_card_details`, `final_review`, or `application_complete`.", "enum": [ "verify_info", "application_questions", "esignature_document", "add_card_details", "final_review", "application_complete" ], "example": "final_review", "readOnly": true, "type": "string" }, "success_url": { "description": "The URL to which 1099Policy should direct independent contractors when a contractor successfully procures insurance coverage. ", "example": "https://1099jobcloud.com/1099policy/success", "type": "string" }, "url": { "description": "The URL to the insurance application Session. Redirect customers to this URL to take them to their insurance application. The domain will use apply.1099policy.com.", "example": "http://apply.1099policy.com/...", "readOnly": true, "type": "string" } }, "type": "object" }, "Webhook": { "description": "Webhooks are a way for 1099Policy to communicate with your server. To receive events you can use the `webhook_endpoints` API to register your webhook endpoints.\n\nIf you prefer, you can also register and configure your webhook endpoints from the [dashboard](https://dashboard.1099policy.com/webhooks).\n\nWhen an event occurs, we'll send an HTTP POST request to the registered webhook endpoint. We'll notify your server about events that happen in your 1099Policy account, such as when a contractor starts an insurance application or when a policy is issued.", "properties": { "created": { "allOf": [ { "$ref": "#/components/schemas/Created" } ], "example": "2024-01-06T05:30:39.373Z" }, "description": { "description": "Optional human-readable description of the endpoint. ", "type": "string" }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" } ], "example": "whe_KPGc5vEZdvoETu39BNwu2Z" }, "secret": { "description": "Webhook secret which you can use to verify that the webhook is from 1099Policy. Read more about how to use the webhook secret to verify the webhook signature in our documentation [here](/content/docs/automating-compliance#webhook-signature-verification/index.html).", "example": "whr_a_secret_key", "type": "string" }, "url": { "description": "The URL of the webhook endpoint.", "example": "https://example.com/my/webhook/endpoint", "type": "string" } }, "type": "object" } } }, "definitions": {}, "info": { "description": "The 1099Policy API is based on REST principles with resource-oriented URLs that accept JSON request bodies and return JSON responses. Use the 1099Policy API and the keys available on your 1099Policy Dashboard to offer contractors on your platform access to on-demand, pay-as-you-go insurance.\n\nUse the development environment secret key to step through the process of procuring insurance using 1099Policy API for test contractors and job assignments. Because the API key you use to authenticate determines whether the request runs in our production environment or in our development environment, going live on the 1099Policy platform is as easy as replacing the development secret key with the production secret key once you're ready.", "title": "1099Policy API Reference", "version": "1.12", "x-logo": { "altText": "1099Policy Logo", "backgroundColor": "#ffffff", "url": "https://www.1099policy.com/img/1099Policy-logo-api.svg" } }, "openapi": "3.2.0", "paths": { "/api/v1/apply/sessions": { "get": { "description": "\nReturns a list of insurance application Sessions.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination. `starting_after` is an application session ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `ias_fOo123`, your subsequent call can include `starting_after=ias_fOo123` in order to fetch the next page of the list.", "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for use in pagination. `ending_before` is an application session ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `ias_bAr123`, your subsequent call can include `ending_before=ias_bAr123` in order to fetch the previous page of the list.", "in": "query", "name": "ending_before", "required": false, "schema": { "type": "string" } }, { "description": "Filter sessions by contractor ID (e.g., `cn_Ehb3bYa`).", "in": "query", "name": "contractor", "required": false, "schema": { "type": "string" } }, { "description": "Filter sessions by general opt-in flag. Set to `true` to return only general opt-in sessions, `false` to return only standard sessions, or omit to return all sessions.", "in": "query", "name": "is_general_opt_in", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Session" }, "type": "array" } } }, "description": "Returns an array of session objects. If no more sessions are available, the resulting array will be empty." } }, "summary": "List all sessions", "tags": [ "Session" ] }, "post": { "description": "\nCreates a session object.\n", "requestBody": { "content": { "application/json": { "schema": { "properties": { "cancel_url": { "description": "The URL the contractor will be directed to if they are ineligible or decide to abandon the insurance application and return to your website.", "type": "string" }, "contractor": { "description": "The ID of the contractor (required for general opt-in sessions). For standard sessions, this is derived from the quote.", "type": "string" }, "general_opt_in_work_state": { "description": "The work state for general opt-in sessions (e.g., \"CA\", \"NY\"). Required when `is_general_opt_in` is `true`.", "type": "string" }, "is_general_opt_in": { "description": "Set to `true` to create a general opt-in session (not tied to a specific job/quote). When `true`, `contractor` and `work_state` are required, and `quote` is not required.", "type": "boolean" }, "quote": { "description": "The ID of an existing quote to be associated with the insurance application session.", "type": "string" }, "success_url": { "description": "The URL to which 1099Policy should direct independent contractors when a contractor successfully procures insurance coverage.", "type": "string" } }, "required": [ "quote" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Returns the session object for an insurance application if quote, job, and contractor are valid." } }, "summary": "Create a session", "tags": [ "Session" ] } }, "/api/v1/apply/sessions/{session}": { "get": { "description": "\nRetrieves the insurance application session with the given ID.\n", "parameters": [ { "description": "The ID of the desired session (e.g., `ias_01FVCHXE7PNQHA1T3S2AXL2QZE`).", "in": "path", "name": "session", "required": true, "schema": { "example": "ias_01FVCHXE7PNQHA1T3S2AXL2QZE", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Returns a session object if a valid session ID was provided. Returns an error otherwise." } }, "summary": "Retrieve a session", "tags": [ "Session" ] }, "put": { "description": "\nUpdates the success_url and cancel_url of a specified session. If\neither parameters is not provided it will be left unchanged.\n\n", "parameters": [ { "description": "The ID of the desired session (e.g., `ias_01FVCHXE7PNQHA1T3S2AXL2QZE`).", "in": "path", "name": "session", "required": true, "schema": { "example": "ias_01FVCHXE7PNQHA1T3S2AXL2QZE", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "cancel_url": "https://example.com/cancel", "success_url": "https://example.com/success" }, "properties": { "cancel_url": { "description": "The URL the contractor will be directed to if they are ineligible or decide to abandon the insurance application and return to your website.", "type": "string" }, "success_url": { "description": "The URL to which 1099Policy should direct independent contractors when a contractor successfully procures insurance coverage.", "type": "string" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Returns the updated session object." } }, "summary": "Update a session", "tags": [ "Session" ] } }, "/api/v1/apply/sessions/{session}/expire": { "post": { "description": "\nExpires the insurance application session with the given ID.\nAn insurance application session can't be expired if the\napplication status is complete.\n\nAfter it expires, a contractor can’t complete an insurance application\nsession and contractors loading the insurance application session see\na message saying the insurance application session is expired.\n", "parameters": [ { "description": "The ID of the desired session (e.g., `ias_01FVCHXE7PNQHA1T3S2AXL2QZE`).", "in": "path", "name": "session", "required": true, "schema": { "example": "ias_01FVCHXE7PNQHA1T3S2AXL2QZE", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Returns a session object if the expiration succeeded. Returns an error if the session is already expired or isn't in an expireable state." } }, "summary": "Expire a session", "tags": [ "Session" ] } }, "/api/v1/assignments": { "get": { "description": "\nReturns a list of your assignments. The assigments returned\nare sorted by creation date, with the most recently created\nassignments appearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination. `starting_after` is an assignment ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `asn_fOo123`, your subsequent call can include `starting_after=asn_fOo123` in order to fetch the next page of the list.", "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for use in pagination. `ending_before` is an assignment ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `asn_bAr123`, your subsequent call can include `ending_before=asn_bAr123` in order to fetch the previous page of the list.", "in": "query", "name": "ending_before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Assignment" }, "type": "array" } } }, "description": "Returns an array of assignment objects. If no more assignments are available, the resulting array will be empty." } }, "summary": "List all assignments", "tags": [ "Assignment" ] }, "post": { "description": "\nThis endpoint creates an assignment object that you can use\nto attach insurance coverage to any job assignment a contractor\ntakes after the contractor has gone active on the 1099Policy\nplatform (i.e., after completing thier insurance application\nsuccessfully).\n", "requestBody": { "content": { "application/json": { "schema": { "properties": { "bind": { "description": "Indicates whether to start the process of binding coverage, which includes notifying and subsequently charging the independent contractor for the premium amount due. Defaults to `true`. When false, 1099Policy does not notify or schedule a charge. Note that the independent contractor is not issued coverage if bind is set to `false`.", "type": "boolean" }, "contractor": { "description": "ID of the contractor", "type": "string" }, "coverage_type": { "description": "An array of coverage types that can include one or more of the following insurance coverage values: `general`, `professional`, `workers-comp`, `media`, and `cyber`. If provided, coverage type is factored into the eligibility determination (i.e., does contractor have an active `workers-comp` policy, etc). Defaults to the coverage types of the most recent active policy if `coverage_type` is not provided.", "enum": [ "general", "professional", "workers-comp" ], "items": { "type": "string" }, "type": "array" }, "effective_date": { "description": "The job assignment start date, measured in seconds since the Unix epoch. This date must be set in the future. The default effective_date is the next day.", "type": "integer" }, "end_date": { "description": "The projected job assignment end date, measured in seconds since the Unix epoch. This date must be after the effective date. If the end_date is on the same day as the effective_date, it will automatically be adjusted to the start of the next day. The default end_date is 30 days after the effective date.", "type": "integer" }, "job": { "description": "ID of the job that the contractor was paid to do.", "type": "string" }, "policy": { "description": "ID of the policy that you want attached to the assignment. Defaults to the most recent active policy with a matching job category code, work state and contractor home state.", "type": "string" } }, "required": [ "contractor", "job" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assignment" } } }, "description": "Returns the assignment object if the post succeeded." } }, "summary": "Create an assignment", "tags": [ "Assignment" ] } }, "/api/v1/assignments/cancel": { "post": { "description": "\nCancels an existing assignment based on the provided job ID. If you\nattempt to cancel an assignment after it has started, the request will\nfail. If you need the option to cancel an assignment after its start date,\nplease contact us.\n", "requestBody": { "content": { "application/json": { "schema": { "example": { "job_id": "jb_123abc", "reason": "client_request" }, "properties": { "job_id": { "description": "The ID of the job associated with the assignment", "type": "string" }, "reason": { "description": "Optional reason for cancellation", "type": "string" } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assignment" } } }, "description": "Assignment successfully cancelled" }, "400": { "description": "Invalid request or assignment cannot be cancelled" }, "404": { "description": "No assignment found for the associated job id." } }, "summary": "Cancel an assignment", "tags": [ "Assignment" ] } }, "/api/v1/assignments/change_dates": { "post": { "description": "\nChanges the start (``effective_date``) and/or end date of **bound**\ncoverage for a job. This is the symmetric counterpart to\n``POST /api/v1/assignments/extend``: extend moves the end date out, this\nendpoint can also move the start date forward (shortening coverage from\nthe front) -- e.g. correcting a start date that slipped into the past --\nand it works for both quote- and assignment-backed coverage.\n\nRestrictions mirror what we already enforce: ``effective_date`` must be in\nthe future, strictly after the current start, and before the end date;\n``end_date`` follows the extend rules (on or after the current end, within\na year of the effective date, and coverage not already ended). At least\none of ``effective_date`` / ``end_date`` is required. Changing dates on a\nbound quote via ``PUT /quotes`` is not supported; use this endpoint.\n\n**Certificate of Insurance (COI) regeneration**: COI PDFs are regenerated\nasynchronously to reflect the new dates. The response returns immediately\nwith ``certificate_refresh_pending: true``; the ``certificate`` URLs in\nthe response are stale, and fresh URLs are published in the\n``assignment.dates_changed`` webhook (and available via the API) once\nregeneration completes.\n", "requestBody": { "content": { "application/json": { "schema": { "example": { "effective_date": 1784332800, "job_id": "jb_jsb9KEcTpc", "send_email": true }, "properties": { "effective_date": { "description": "New coverage start date (seconds since the Unix epoch). Must be in the future, after the current start, and before the end date. Moving it forward shortens coverage from the start.", "format": "int64", "type": "integer" }, "end_date": { "description": "New coverage end date (seconds since the Unix epoch). Must be on or after the current end date and within one year of the effective date.", "format": "int64", "type": "integer" }, "job_id": { "description": "The ID of the job associated with the coverage.", "type": "string" }, "send_email": { "default": true, "description": "When true, email the contractor a coverage-dates-changed notice. COI regeneration and webhook publication happen regardless of this flag.", "type": "boolean" } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Assignment" }, { "$ref": "#/components/schemas/Quote" } ] } } }, "description": "Coverage dates updated, or unchanged (no-op) when the submitted dates match the current values. COIs regenerate asynchronously, so the response includes ``certificate_refresh_pending: true``." }, "400": { "description": "Invalid input, no dates provided, voided/cancelled/unbound record, expired coverage, a backward or past effective_date, or a shortened end_date." }, "404": { "description": "Job not found, or no bound coverage found for the job." } }, "summary": "Change bound coverage dates", "tags": [ "Assignment" ] } }, "/api/v1/assignments/extend": { "post": { "description": "\nExtends an existing assignment based on the provided job ID. Sets a new end date\nfor bound coverage. If you attempt to extend after coverage has ended, or the\nend date is invalid, the request will fail. Updating ``end_date`` on a bound\nassignment via ``PUT`` is not supported; use this endpoint instead.\n\n**Certificate of Insurance (COI) regeneration**: When extending coverage, COI PDFs\nare regenerated asynchronously to reflect the new end date. The response returns\nimmediately with ``certificate_refresh_pending: true``, indicating that:\n\n- The ``certificate`` URLs in the response point to the old PDFs (pre-regeneration)\n- Fresh certificate URLs will be included in the ``assignment.extended``\n webhook, which is published after COI regeneration completes\n- Fresh URLs can also be fetched via the API after background processing finishes\n\nThis async design ensures the API responds quickly without blocking for PDF generation.\n", "requestBody": { "content": { "application/json": { "schema": { "example": { "end_date": 1735689600, "job_id": "jb_jsb9KEcTpc", "send_email": true }, "properties": { "end_date": { "description": "New end date for the assignment, measured in seconds since the Unix epoch. Must be on or after the current end date and within one year of the effective date.", "format": "int64", "type": "integer" }, "job_id": { "description": "The ID of the job associated with the assignment", "type": "string" }, "send_email": { "default": true, "description": "When true, send a coverage-extension notification email to the contractor. COI regeneration and webhook publication happen regardless of this flag.", "type": "boolean" } }, "required": [ "job_id", "end_date" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Assignment" }, { "$ref": "#/components/schemas/Quote" } ] } } }, "description": "Assignment end date updated, or unchanged (no-op) when ``end_date`` matches the current value. COIs are always regenerated asynchronously, so the response includes ``certificate_refresh_pending: true`` to indicate that certificate URLs are stale and fresh URLs will be available in the webhook." }, "400": { "description": "Invalid input, voided or cancelled record, expired coverage, attempted shortening, or same end date when no-op is not allowed." }, "404": { "description": "Job not found, or no assignment found for the associated job id." } }, "summary": "Extend an assignment", "tags": [ "Assignment" ] } }, "/api/v1/assignments/media": { "get": { "description": "\nRetrieves all media coverage records associated with a policy.\n", "parameters": [ { "description": "The ID of the policy to get media coverage records for.", "in": "query", "name": "policy_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MediaCoverage" }, "type": "array" } } }, "description": "Returns a list of media coverage records if successful." }, "400": { "description": "Returns an error if the policy_id parameter is missing or invalid." }, "404": { "description": "Returns an error if the specified policy is not found." }, "500": { "description": "Returns an error if there was an internal server error." } }, "summary": "Get media coverage records for a policy", "tags": [ "Assignment" ] }, "post": { "description": "\nCreates a new media coverage record for a policy and adds published content.\nThe media coverage record is used to track content published by contractors\nand generate Certificates of Insurance (COIs) for media coverage.\n", "requestBody": { "content": { "application/json": { "schema": { "example": { "policy_id": "pl_123abc", "publication_date": 1711612800, "published_content_json": { "additional_field": "any value", "platform": "instagram", "url": "https://instagram.com/pl/1234567890" } }, "properties": { "policy_id": { "description": "The ID of the policy to associate with the media coverage record.", "type": "string" }, "publication_date": { "description": "The date and time when the content was published, in seconds since the Unix epoch.", "type": "integer" }, "published_content_json": { "description": "Details about the published content. Can contain any valid JSON structure.", "type": "object" } }, "required": [ "publication_date", "policy_id", "published_content_json" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaCoverage" } } }, "description": "Returns the created media coverage record if successful." }, "400": { "description": "Returns an error if required fields are missing or invalid." }, "404": { "description": "Returns an error if the specified policy is not found." }, "500": { "description": "Returns an error if there was an internal server error." } }, "summary": "Create a media coverage record for an assignment", "tags": [ "Assignment" ] } }, "/api/v1/assignments/{assignment}": { "delete": { "description": "\nPermanently deletes an assignment. This cannot be undone.\nAttempts to delete assignments with jobs that have invoices\npaid in full will fail.\n", "parameters": [ { "description": "The ID of the desired assignment (e.g., `an_G5biPgc5Hc`).", "in": "path", "name": "assignment", "required": true, "schema": { "example": "an_G5biPgc5Hc", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "deleted": true, "deleted_at": 1640995200, "id": "an_G5biPgc5Hc", "object": "assignment" }, "properties": { "deleted": { "type": "boolean" }, "deleted_at": { "description": "Unix timestamp (seconds since epoch) of when the assignment was deleted.", "type": "integer" }, "id": { "description": "The assignment ID.", "type": "string" }, "object": { "default": "assignment", "type": "string" } } } } }, "description": "A successfully deleted assignment. Otherwise, this call returns an error, such as if the assignment has already been deleted." } }, "summary": "Delete an assignment", "tags": [ "Assignment" ] }, "get": { "description": "\nRetrieves the assignment with the given ID.\n", "parameters": [ { "description": "The ID of the desired assignment (e.g., `an_G5biPgc5Hc`).", "in": "path", "name": "assignment", "required": true, "schema": { "example": "an_G5biPgc5Hc", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assignment" } } }, "description": "Returns an assignment object if a valid assignment ID was provided. Returns an error otherwise." } }, "summary": "Retrieve an assignment", "tags": [ "Assignment" ] }, "put": { "description": "\nAssignments are editable up until the related invoice\nis paid in full.\n", "parameters": [ { "description": "The ID of the desired assignment (e.g., `an_3mqtUPL2cA`).", "in": "path", "name": "assignment", "required": true, "schema": { "example": "an_3mqtUPL2cA", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "bind": true, "contractor": "cn_Ehb3bYa", "coverage_type": [ "general", "workers-comp" ], "effective_date": 1646818364, "end_date": 1646818364, "job": "jb_jsb9KEcTpc", "policy": "pl_3mqtUPL2cA" }, "properties": { "bind": { "description": "Indicates whether to start the process of binding coverage, which includes notifying and subsequently charging the independent contractor for the premium amount due. Defaults to `true`. When false, 1099Policy does not notify or schedule a charge. Note that the independent contractor is not issued coverage if bind is set to `false`.", "type": "boolean" }, "contractor": { "description": "ID of the contractor", "type": "string" }, "coverage_type": { "description": "An array of coverage types that can include one or more of the following insurance coverage values: `general`, `workers-comp`, and `professional`. If provided, coverage type is factored into the eligibility determination (i.e., does contractor have an active `workers-comp` policy, etc). Defaults to the coverage types of the most recent active policy if `coverage_type` is not provided.", "items": { "enum": [ "general", "workers-comp", "professional" ], "type": "string" }, "type": "array" }, "effective_date": { "description": "The job assignment start date, measured in seconds since the Unix epoch.", "type": "integer" }, "end_date": { "description": "The projected job assignment end date, measured in seconds since the Unix epoch. If the end_date is on the same day as the effective_date, it will automatically be adjusted to the start of the next day.", "type": "integer" }, "job": { "description": "ID of the job that the contractor intends to accept.", "type": "string" }, "policy": { "description": "ID of the policy that you want attached to the assignment. Defaults to the most recent active policy with a matching job category code, work state and contractor home state.", "type": "string" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assignment" } } }, "description": "Returns an invoice object if a valid invoice ID was provided. Returns an error otherwise." } }, "summary": "Update an assignment", "tags": [ "Assignment" ] } }, "/api/v1/category_codes": { "get": { "description": "\nReturns a list of your approved job category codes. The job category\ncodes are returned sorted by approval date, with the most recently\napproved job categories appearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CategoryCodes" }, "type": "array" } } }, "description": "Returns an array of job category code objects. If no more job category codes are available, the resulting array will be empty." } }, "summary": "List all category codes", "tags": [ "Category Code" ] } }, "/api/v1/contractors": { "get": { "description": "\nReturns a list of your contractors. The contractors are\nreturned sorted by creation date, with the most recent\ncontractors appearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination. `starting_after` is an contractor ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `cn_fOo123`, your subsequent call can include `starting_after=cn_fOo123` in order to fetch the next page of the list.", "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for use in pagination. `ending_before` is an contractor ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `cn_bAr123`, your subsequent call can include `ending_before=cn_bAr123` in order to fetch the previous page of the list.", "in": "query", "name": "ending_before", "required": false, "schema": { "type": "string" } }, { "description": "A case-sensitive filter on the list based on the contractor's email attribute. The value must be a string.", "explode": true, "in": "query", "name": "email", "required": false, "schema": { "example": "billscot@example.com", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Contractor" }, "type": "array" } } }, "description": "Returns an array of contractor objects. If no more contractors are available, the resulting array will be empty." } }, "summary": "List all contractors", "tags": [ "Contractor" ] }, "post": { "description": "\nCreates a new contractor object.\n", "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "description": "The contractor's home address.", "required": [ "line1", "locality", "region", "postalcode" ], "type": "object" } ] }, "company_name": { "description": "The contractor's business name.", "type": "string" }, "custom_metadata": { "description": "Set of key-value pairs that you can attach to an object. Used to store additional information about the contractor in a structured format.", "type": "object" }, "email": { "description": "The contractor's email address.", "type": "string" }, "first_name": { "description": "The contractor's first name.", "type": "string" }, "last_name": { "description": "The contractor's last name.", "type": "string" }, "middle_name": { "description": "The contractor's middle name.", "type": "string" }, "phone": { "description": "The contractor's phone number.", "type": "string" }, "tax_identification": { "description": "The contractor's tax identification number. For example, an employer identification number (EIN) if the contractor operates as a corporate entity or a social security number if the contractor operates as a sole proprietor.", "type": "string" }, "withhold_premium": { "description": "This indicates whether the contractor is paying premium directly with their credit card (i.e., `false`) or if the contractor has given the platform that's integrating with 1099Policy permission to withhold the premium payment from their wages and pay the premium on the contractor's behalf (i.e., `true`). Defaults to `false`.", "type": "boolean" } }, "required": [ "first_name", "last_name", "email", "address" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contractor" } } }, "description": "Returns the contractor object if the post succeeded." } }, "summary": "Create a contractor", "tags": [ "Contractor" ] } }, "/api/v1/contractors/{contractor}": { "delete": { "description": "\nPermanently deletes a contractor. It cannot be undone.\nAlso immediately cancels any active policies connected\nwith the contractor.\n", "parameters": [ { "description": "The ID of the desired contractor (e.g., `cn_Ehb3bYa`).", "in": "path", "name": "contractor", "required": true, "schema": { "example": "cn_Ehb3bYa", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "deleted": true, "deleted_at": 1640995200, "id": "cn_Ehb3bYa", "object": "contractor" }, "properties": { "deleted": { "type": "boolean" }, "deleted_at": { "description": "Unix timestamp (seconds since epoch) of when the contractor was deleted.", "type": "integer" }, "id": { "description": "The contractor ID.", "type": "string" }, "object": { "default": "contractor", "type": "string" } } } } }, "description": "Returns an object with a deleted parameter on success. If the contractor ID does not exist, this call returns an error." } }, "summary": "Delete a contractor", "tags": [ "Contractor" ] }, "get": { "description": "\nRetrieves the details of an existing contractor.\nYou need only supply the unique contractor identifier\nthat was returned upon contractor creation.\n", "parameters": [ { "description": "The ID of the desired contractor (e.g., `cn_Ehb3bYa`).", "in": "path", "name": "contractor", "required": true, "schema": { "example": "cn_Ehb3bYa", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contractor" } } }, "description": "Returns a contractor object if a valid identifier was provided." } }, "summary": "Retrieve a contractor", "tags": [ "Contractor" ] }, "put": { "description": "\nUpdates the specified contractor by setting the values\nof the parameters passed. Any parameters not provided\nwill be left unchanged.\n\nThis request accepts mostly the same arguments as the\ncontractor creation call.\n", "parameters": [ { "description": "The ID of the desired contractor (e.g., `cn_Ehb3bYa`).", "in": "path", "name": "contractor", "required": true, "schema": { "example": "cn_Ehb3bYa", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "address": { "line1": "123 Main St.", "locality": "San Francisco", "postalcode": "94105", "region": "CA" }, "company_name": "Acme Co.", "custom_metadata": { "campaign": "Red Bull" }, "email": "parker@gmail.com", "first_name": "Joe", "last_name": "Parker", "middle_name": "Doe", "phone": "415-474-9088" }, "schema": { "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" } ], "description": "The contractor's home address." }, "company_name": { "description": "The contractor's business name.", "type": "string" }, "custom_metadata": { "description": "Set of key-value pairs that you can attach to an object. Used to store additional information about the contractor in a structured format. Individual keys can be unset by posting an empty value to them. Pass an empty value, e.g. {}, to custom_metadata to unset all keys.", "type": "object" }, "email": { "description": "The contractor's email address.", "type": "string" }, "first_name": { "description": "The contractor's first name.", "type": "string" }, "last_name": { "description": "The contractor's last name.", "type": "string" }, "middle_name": { "description": "The contractor's middle name.", "type": "string" }, "phone": { "description": "The contractor's phone number.", "type": "string" }, "withhold_premium": { "description": "This indicates whether the contractor is paying premium directly with their credit card (i.e., `false`) or if the contractor has given the platform that's integrating with 1099Policy permission to withhold the premium payment from their wages and pay the premium on the contractor's behalf (i.e., `true`). Defaults to `false`.", "type": "boolean" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contractor" } } }, "description": "Returns the contractor object if the update succeeded. Returns an error if update parameters are invalid." } }, "summary": "Update a contractor", "tags": [ "Contractor" ] } }, "/api/v1/contractors/{contractor}/login_link": { "post": { "description": "\nGenerates a secure, time-limited login URL for contractor portal access.\nThis allows agencies to provide direct portal access without requiring\ncontractors to go through email verification.\n", "parameters": [ { "description": "The contractor's public ID", "in": "path", "name": "contractor", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "redirect_url": { "description": "URL to redirect the contractor to after successful authentication. Must match an allowlisted origin.", "example": "https://my.1099policy.com/insurance/start", "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "contractor": { "properties": { "company_name": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "id": { "type": "integer" }, "last_name": { "type": "string" }, "public_id": { "type": "string" } }, "type": "object" }, "expires_at": { "description": "Time at which the login token expires. Measured in seconds since the Unix epoch.", "example": 1765555200, "format": "int64", "type": "integer" }, "login_url": { "description": "Complete login URL with embedded token", "example": "https://my.1099policy.com/quick-access?contractor_id=cn_abc123&token=xyz789", "type": "string" }, "success": { "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Login link generated successfully" }, "400": { "description": "Contractor has no email address, or the supplied redirect_url is not an allowlisted origin." }, "404": { "description": "Contractor not found" }, "500": { "description": "Failed to generate login link" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Generate login link", "tags": [ "Contractor" ] } }, "/api/v1/contractors/{contractor}/policies": { "get": { "description": "\nReturns a list of policies for a given contractor.\n", "parameters": [ { "description": "The ID of the desired contractor (e.g., `cn_Ehb3bYa`).", "in": "path", "name": "contractor", "required": true, "schema": { "example": "cn_Ehb3bYa", "type": "string" } }, { "description": "A filter to return policies by a specific quote ID.", "in": "query", "name": "quote", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Policy" }, "type": "array" } } }, "description": "Returns a list of the contractors policies. The policies are returned sorted by creation date, with the most recent policy appearing first." } }, "summary": "List a contractor's policies", "tags": [ "Policy" ] } }, "/api/v1/entities": { "get": { "description": "\nReturns a list of your contracting entities. The entities\nare returned sorted by creation date, with the most recent\nentities appearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination. `starting_after` is an entity ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `en_fOo123`, your subsequent call can include `starting_after=en_fOo123` in order to fetch the next page of the list.", "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for use in pagination. `ending_before` is an entity ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `en_bAr123`, your subsequent call can include `ending_before=en_bAr123` in order to fetch the previous page of the list.", "in": "query", "name": "ending_before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Entity" }, "type": "array" } } }, "description": "Returns an array of entity objects. If no more entities are available, the resulting array will be empty." } }, "summary": "List all entities", "tags": [ "Entity" ] }, "post": { "description": "\nCreates a new contracting entity object.\n", "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "description": "The contracting entity's address.", "type": "object" } ] }, "coverage_limit": { "allOf": [ { "$ref": "#/components/schemas/Limit" }, { "description": "The contracting entity's minimum required coverage limits.", "type": "object" } ] }, "name": { "description": "The contracting entity's legal name.", "type": "string" }, "required_coverage": { "$ref": "#/components/schemas/Coverage" } }, "required": [ "name" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } }, "description": "Returns the entity object if the post succeeded." } }, "summary": "Create an entity", "tags": [ "Entity" ] } }, "/api/v1/entities/{entity}": { "delete": { "description": "\nPermanently deletes an entity. It cannot be undone.\nAlso immediately cancels any insurance policies\nconnected with active jobs managed by the entity.\n", "parameters": [ { "description": "The ID of the desired entity (e.g., `en_Ah3tqYn`).", "in": "path", "name": "entity", "required": true, "schema": { "example": "en_Ah3tqYn", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "deleted": true, "deleted_at": 1640995200, "id": "en_Ah3tqYn", "object": "entity" }, "properties": { "deleted": { "type": "boolean" }, "deleted_at": { "description": "Unix timestamp (seconds since epoch) of when the entity was deleted.", "type": "integer" }, "id": { "description": "The entity ID.", "type": "string" }, "object": { "default": "entity", "type": "string" } } } } }, "description": "A successfully deleted entity. Otherwise, this call returns an error, such as if the entity has already been deleted." } }, "summary": "Delete an entity", "tags": [ "Entity" ] }, "get": { "description": "\nRetrieves the details of an existing entity.\nYou need only supply the unique entity ID\nthat was returned upon entity creation.\n", "parameters": [ { "description": "The ID of the desired entity (e.g., `en_Ah3tqYn`).", "in": "path", "name": "entity", "required": true, "schema": { "example": "en_Ah3tqYn", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } }, "description": "Returns an entity object if a valid entity ID was provided. Returns an error otherwise." } }, "summary": "Retrieve an entity", "tags": [ "Entity" ] }, "put": { "description": "\nUpdates the specified entity by setting the values\nof the parameters passed. Any parameters not provided\nwill be left unchanged.\n\nThis request accepts mostly the same arguments as the\nentity creation call.\n", "parameters": [ { "description": "The ID of the desired entity (e.g., `en_Ah3tqYn`).", "in": "path", "name": "entity", "required": true, "schema": { "example": "en_Ah3tqYn", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" } ], "description": "The contracting entity's address." }, "coverage_limit": { "allOf": [ { "$ref": "#/components/schemas/Limit" } ], "description": "The contracting entity's minimum required coverage limits." }, "name": { "description": "The contracting entity's legal name.", "type": "string" }, "required_coverage": { "$ref": "#/components/schemas/Coverage" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } }, "description": "Returns the entity object if the update succeeded. Returns an error if update parameters are invalid." } }, "summary": "Update an entity", "tags": [ "Entity" ] } }, "/api/v1/events": { "get": { "description": "\nReturns a list of events with pagination (20 events per page).\nThe events are sorted by creation date, with the most recent\nevent appearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Event" }, "type": "array" } } }, "description": "Returns an array of event objects. If no more events are available, the resulting array will be empty." } }, "summary": "List all events", "tags": [ "Event" ] } }, "/api/v1/events/{event}": { "get": { "description": "\nRetrieves the details of an event. You need only\nprovide the unique event ID which you would have\nreceived in a webhook.\n", "parameters": [ { "description": "The ID of the desired event (e.g., `ev_1a2b3c4d5e6f`).", "in": "path", "name": "event", "required": true, "schema": { "example": "ev_1a2b3c4d5e6f", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } }, "description": "Returns an event object if a valid ID was provided." } }, "summary": "Retrieve an event", "tags": [ "Event" ] } }, "/api/v1/files/certificates": { "get": { "description": "\nReturns a list of certificates. The certificates are returned\nsorted by creation date, with the most recently created certificates\nappearing first. Supports pagination using `starting_after` and `ending_before`.\n\n", "parameters": [ { "description": "A limit on the number of objects to be returned. The limit can range between `1` and `100`, and the default is `10`.\n", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination. `starting_after` is a certificate ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `ca_123`, your subsequent call can include `starting_after=ca_123` in order to fetch the next page of the list.\n", "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for use in pagination. `ending_before` is a certificate ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `ca_456`, your subsequent call can include `ending_before=ca_456` in order to fetch the previous page of the list.\n", "in": "query", "name": "ending_before", "required": false, "schema": { "type": "string" } }, { "description": "Specifies which fields in the response should be expanded. Use `expand[]=review_results` for abbreviated review results, or `expand[]=review_results.full` for full review results including parsed certificate data and detailed audit results.\n", "example": [ "review_results", "review_results.full" ], "explode": true, "in": "query", "name": "expand", "required": false, "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Certificate" }, "type": "array" } } }, "description": "Returns an array of certificate objects. If no more certificates are available, the resulting array will be empty.\n" } }, "summary": "List all certificates.", "tags": [ "Certificate" ] }, "post": { "description": "\nUploads a new Certificate of Insurance (COI) PDF file, validates it, and creates\na certificate record. The certificate processing is performed asynchronously in the\nbackground. The initial response indicates that the certificate has been accepted\nfor processing with a status of \"pending\".\n\n**Asynchronous Processing:**\n\nAfter uploading a certificate, the platform automatically processes the document\nand evaluates it against your organization's pre-defined insurance requirements. This\nevaluation happens asynchronously, so the initial response will have:\n- `status`: \"pending\" (indicating processing has not yet started)\n- `review_results`: `null` (will be populated once processing completes)\n\n**Monitoring Certificate Status:**\n\nYou can monitor the certificate status in two ways:\n\n1. **Polling**: Periodically retrieve the certificate using the GET endpoint to check\n the `status` field. The status will transition from \"pending\" → \"processing\" →\n (\"approved\" | \"flagged\" | \"denied\" | \"error\") as processing completes.\n\n2. **Webhooks**: Register a webhook endpoint to receive real-time notifications when\n processing completes. The following events are sent:\n - `certificate.approved` - Certificate passed all requirements\n - `certificate.flagged` - Certificate failed some requirements\n - `certificate.denied` - Certificate was denied\n\n**Retrieving Review Results:**\n\nOnce processing is complete, use the `expand[]=review_results` parameter when\nretrieving the certificate to get abbreviated review results, or\n`expand[]=review_results.full` for complete details including parsed certificate\ndata and detailed audit results.\n\n", "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "certificate": { "description": "The certificate PDF file to be uploaded (max 15MB).", "format": "binary", "type": "string" }, "contractor": { "description": "The ID of the contractor associated with the certificate.", "type": "string" } }, "required": [ "certificate", "contractor" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } }, "description": "Returns the created certificate object. The certificate has been accepted for processing and will have a status of \"pending\". Processing happens asynchronously, and you can monitor the status via polling or webhooks.\n" } }, "summary": "Create a new certificate.", "tags": [ "Certificate" ] } }, "/api/v1/files/certificates/{certificate}": { "delete": { "description": "\nDeletes an existing certificate by its ID.\n\n", "parameters": [ { "description": "The ID of the certificate to delete.", "in": "path", "name": "certificate", "required": true, "schema": { "example": "ci_YnsHeB9PTo", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "deleted": true, "deleted_at": 1640995200, "id": "ci_YnsHeB9PTo", "object": "certificate" }, "properties": { "deleted": { "type": "boolean" }, "deleted_at": { "description": "Unix timestamp (seconds since epoch) of when the certificate was deleted.", "type": "integer" }, "id": { "description": "The certificate ID.", "type": "string" }, "object": { "default": "certificate", "type": "string" } } } } }, "description": "Returns an object with a deleted parameter on success. Otherwise, this call returns an error.\n" } }, "summary": "Delete a certificate.", "tags": [ "Certificate" ] }, "get": { "description": "\nRetrieves the details of an existing certificate by its ID. Use this endpoint\nto poll for certificate status updates during asynchronous processing.\n\n**Certificate Status Lifecycle:**\n\nThe certificate status transitions through the following states:\n- `pending` - Certificate has been uploaded but processing has not started\n- `processing` - Certificate is currently being processed\n- `approved` - Certificate passed all insurance requirements\n- `flagged` - Certificate failed some requirements (may require manual review)\n- `denied` - Certificate was denied\n- `error` - An error occurred during processing\n\n**Retrieving Review Results:**\n\nOnce processing is complete, use the `expand` parameter to retrieve review results:\n- `expand[]=review_results` - Returns abbreviated results with summary counts\n- `expand[]=review_results.full` - Returns full parsed certificate data and detailed\n audit results for each insurance requirement\n\n", "parameters": [ { "description": "The ID of the desired certificate.", "in": "path", "name": "certificate", "required": true, "schema": { "example": "ci_YnsHeB9PTo", "type": "string" } }, { "description": "Specifies which fields in the response should be expanded. Use `expand[]=review_results` for abbreviated review results, or `expand[]=review_results.full` for full review results including parsed certificate data and detailed audit results.\n", "example": [ "review_results", "review_results.full" ], "explode": true, "in": "query", "name": "expand", "required": false, "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } }, "description": "Returns a certificate object if a valid certificate ID was provided. The `status` field indicates the current processing state, and `review_results` will be `null` until processing completes.\n" }, "404": { "description": "Certificate not found" } }, "summary": "Retrieve a certificate.", "tags": [ "Certificate" ] } }, "/api/v1/invoices": { "get": { "description": "\nYou can list all invoices, or list the invoices for a\nspecific contractor. The invoices are returned sorted\nby creation date, with the most recently created invoices\nappearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination. `starting_after` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `in_fOo123`, your subsequent call can include `starting_after=in_fOo123` in order to fetch the next page of the list.", "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for use in pagination. `ending_before` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `in_bAr123`, your subsequent call can include `ending_before=in_bAr123` in order to fetch the previous page of the list.", "in": "query", "name": "ending_before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Invoice" }, "type": "array" } } }, "description": "Returns an array of invoice objects. If no more invoices are available, the resulting array will be empty." } }, "summary": "List all invoices", "tags": [ "Invoice" ] }, "post": { "description": "\nThis endpoint creates an invoice that reflects the insurance premium\nowed by the contractor for the specified pay period.\n", "requestBody": { "content": { "application/json": { "schema": { "properties": { "contractor": { "description": "ID of the contractor", "type": "string" }, "gross_pay": { "description": "The gross pay that the contractor earned in the last pay period.", "type": "integer" }, "job": { "description": "ID of the job that the contractor was paid to do.", "type": "string" }, "paycycle_enddate": { "description": "Pay period end date.", "type": "integer" }, "paycycle_startdate": { "description": "Pay period start date.", "type": "integer" }, "purchase_order_number": { "description": "The purchase order number for this invoice. Optional.\n\nBy default an invoice inherits the `purchase_order_number` set on the job's `custom_metadata`. Send this field to override that default for this invoice — an explicit value always wins over the job default. Send an empty string (`\"\"`) to create the invoice with no purchase order number, or omit the field to inherit the job's default.\n\nIf a later gross_pay change re-prices this invoice, the replacement invoice keeps this purchase order number; it is not re-inherited from the job.", "type": "string" } }, "required": [ "contractor", "job", "gross_pay", "paycycle_startdate", "paycycle_enddate" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Returns the invoice object if the post succeeded." } }, "summary": "Create an invoice", "tags": [ "Invoice" ] } }, "/api/v1/invoices/{invoice}": { "delete": { "description": "\nPermanently deletes an invoice. This cannot be undone.\nAttempts to delete invoices that have been paid will fail.\n", "parameters": [ { "description": "The ID of the desired invoice (e.g., `in_4RviYgc2Wt`).", "in": "path", "name": "invoice", "required": true, "schema": { "example": "in_4RviYgc2Wt", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "deleted": true, "deleted_at": 1640995200, "id": "in_4RviYgc2Wt", "object": "invoice" }, "properties": { "deleted": { "type": "boolean" }, "deleted_at": { "description": "Unix timestamp (seconds since epoch) of when the invoice was deleted.", "type": "integer" }, "id": { "description": "The invoice ID.", "type": "string" }, "object": { "default": "invoice", "type": "string" } } } } }, "description": "A successfully deleted invoice. Otherwise, this call returns an error, such as if the invoice has already been deleted." } }, "summary": "Delete an unpaid invoice", "tags": [ "Invoice" ] }, "get": { "description": "\nRetrieves the invoice with the given ID.\n", "parameters": [ { "description": "The ID of the desired invoice (e.g., `in_4RviYgc2Wt`).", "in": "path", "name": "invoice", "required": true, "schema": { "example": "in_4RviYgc2Wt", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Returns an invoice object if a valid invoice ID was provided. Returns an error otherwise." } }, "summary": "Retrieve an invoice", "tags": [ "Invoice" ] }, "put": { "description": "\nInvoices that haven't been paid are fully editable.\nOnce an invoice is paid, it becomes uneditable.\n", "parameters": [ { "description": "The ID of the desired invoice (e.g., `in_4RviYgc2Wt`).", "in": "path", "name": "invoice", "required": true, "schema": { "example": "in_4RviYgc2Wt", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "contractor": "cn_Ehb3bYa", "gross_pay": 10000, "job": "jb_jsb9KEcTpc", "paycycle_enddate": 1678334737, "paycycle_startdate": 1646818364, "purchase_order_number": "PO-12345678" }, "schema": { "properties": { "contractor": { "description": "ID of the contractor", "type": "string" }, "gross_pay": { "description": "The gross pay that the contractor earned in the last pay period.", "type": "integer" }, "job": { "description": "ID of the job that the contractor was paid to do.", "type": "string" }, "paycycle_enddate": { "description": "Pay period end date.", "type": "integer" }, "paycycle_startdate": { "description": "Pay period start date.", "type": "integer" }, "purchase_order_number": { "description": "The purchase order number for this invoice. Optional.\n\nProvide a value to set or change it — an explicit value overrides the default inherited from the job's `custom_metadata`. Send an empty string (`\"\"`) to clear it, or omit the field to leave the current value unchanged. This is how you change only the purchase order number when nothing else about the invoice has changed. Not editable once the invoice is paid in full.", "type": "string" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Returns an invoice object if a valid invoice ID was provided. Returns an error otherwise." } }, "summary": "Update an invoice", "tags": [ "Invoice" ] } }, "/api/v1/jobs": { "get": { "description": "\nReturns a list of your jobs. The jobs are returned\nsorted by creation date, with the most recently created\njobs appearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination. `starting_after` is an job ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `jb_fOo123`, your subsequent call can include `starting_after=jb_fOo123` in order to fetch the next page of the list.", "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for use in pagination. `ending_before` is an job ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `jb_bAr123`, your subsequent call can include `ending_before=jb_bAr123` in order to fetch the previous page of the list.", "in": "query", "name": "ending_before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Job" }, "type": "array" } } }, "description": "Returns an array of job objects. If no more jobs are available, the resulting array will be empty." } }, "summary": "List all jobs", "tags": [ "Job" ] }, "post": { "description": "\nCreates a new job object. Used to classify\nthe work that 1099Policy applies to insure the\ncontractor.\n", "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "description": "The job address where the work will be done. Exclude if job will be done remotely.", "required": [ "region" ], "type": "object" } ] }, "category_code": { "description": "The category code that 1099Policy creates for a group of similarly classified jobs.\n\nJob category codes are pre-approved by 1099Policy so you can offer contractors insurance to new jobs on your platform in real time.\n\nTo generate pre-approved category codes for a group of similarly classified jobs visit the [1099Policy Dashboard](https://dashboard.1099policy.com/jobs).", "type": "string" }, "custom_metadata": { "description": "Set of key-value pairs that you can attach to an object. Used to store additional information about the job in a structured format.\n\nThe `purchase_order_number` key is recognized: invoices created for this job inherit it as their purchase order number (overridable or clearable per invoice via the invoice endpoints).", "type": "object" }, "description": { "description": "A description of the job that includes the role, responsibilities and necessary qualifications.", "type": "string" }, "entity": { "description": "The ID of an existing entity for whom the job is being done.", "type": "string" }, "name": { "description": "The name of the contractor job role.", "type": "string" }, "wage": { "description": "A positive integer representing the wage (e.g., 1500 cents is $15.00). The minimum wage amount is $1.00 US.", "minimum": 100, "type": "integer" }, "wage_type": { "description": "One of `flatfee`, `hourly`, `unit` or `blended`.", "enum": [ "flatfee", "hourly", "unit", "blended" ], "type": "string" }, "withhold_premium": { "description": "This indicates whether the contractor is paying premium directly with their credit card (i.e., `false`) or if the contractor has given the platform that's integrating with 1099Policy permission to withhold the premium payment from their wages and pay the premium on the contractor's behalf (i.e., `true`). Defaults to `false`.", "type": "boolean" }, "years_experience": { "description": "The number of years of experience required to be eligible for the job.", "type": "integer" } }, "required": [ "name", "description", "wage_type", "wage", "entity", "category_code" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } }, "description": "Returns the job object if the post succeeded." } }, "summary": "Create a job", "tags": [ "Job" ] } }, "/api/v1/jobs/{job}": { "delete": { "description": "\nDelete a job. Deleting a job is only possible if it\nhas no insurance policies associated with it.\n", "parameters": [ { "description": "The ID of the desired job (e.g., `jb_jsb9KEcTpc`).", "in": "path", "name": "job", "required": true, "schema": { "example": "jb_jsb9KEcTpc", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "deleted": true, "deleted_at": 1640995200, "id": "jb_jsb9KEcTpc", "object": "job" }, "properties": { "deleted": { "type": "boolean" }, "deleted_at": { "description": "Unix timestamp (seconds since epoch) of when the job was deleted.", "type": "integer" }, "id": { "description": "The job ID.", "type": "string" }, "object": { "default": "job", "type": "string" } } } } }, "description": "Returns an object with a deleted parameter on success. Otherwise, this call returns an error." } }, "summary": "Delete a job", "tags": [ "Job" ] }, "get": { "description": "\nRetrieves the details of an existing job.\nSupply the unique job ID from either a job\ncreation request or the job list, and 1099Policy\nwill return the corresponding job information.\n", "parameters": [ { "description": "The ID of the desired job (e.g., `jb_jsb9KEcTpc`).", "in": "path", "name": "job", "required": true, "schema": { "example": "jb_jsb9KEcTpc", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } }, "description": "Returns a job object if a valid job ID was provided. Returns an error otherwise." } }, "summary": "Retrieve a job", "tags": [ "Job" ] }, "put": { "description": "\nUpdates the specific job by setting the values of the\nparameters passed. Any parameters not provided will be\nleft unchanged.\n", "parameters": [ { "description": "The ID of the desired job (e.g., `jb_jsb9KEcTpc`).", "in": "path", "name": "job", "required": true, "schema": { "example": "jb_jsb9KEcTpc", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "address": { "line1": "123 Main St", "locality": "San Francisco", "postalcode": 94105, "region": "CA" }, "description": "Install fiber optic cable from back to the front of the store.", "entity": "en_Ah3tqYn", "name": "Field technician", "wage": 1500, "wage_type": "hourly", "years_experience": 5 }, "schema": { "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" } ], "description": "The job address where the work will be done. Exclude if job will be done remotely." }, "custom_metadata": { "description": "Set of key-value pairs that you can attach to an object. Used to store additional information about the job in a structured format.\n\nThe `purchase_order_number` key is recognized: invoices created for this job inherit it as their purchase order number (overridable or clearable per invoice via the invoice endpoints).", "type": "object" }, "description": { "description": "A description of the job that includes the role, responsibilities and necessary qualifications.", "type": "string" }, "entity": { "description": "The ID of an existing entity for whom the job is being done.", "type": "string" }, "name": { "description": "The name of the contractor job role.", "type": "string" }, "wage": { "description": "A positive integer representing the wage (e.g., 1500 cents is $15.00). The minimum wage amount is 100 cents US. The maximum wage amount is 1000000000 cents US ($10,000,000).", "maximum": 1000000000, "minimum": 100, "type": "integer" }, "wage_type": { "description": "One of `flatfee`, `hourly`, `unit` or `blended`.", "enum": [ "flatfee", "hourly", "unit", "blended" ], "type": "string" }, "withhold_premium": { "description": "This indicates whether the contractor is paying premium directly with their credit card (i.e., `false`) or if the contractor has given the platform that's integrating with 1099Policy permission to withhold the premium payment from their wages and pay the premium on the contractor's behalf (i.e., `true`). Defaults to `false`.", "type": "boolean" }, "years_experience": { "description": "The number of years of experience required to be eligible for the job.", "type": "integer" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } }, "description": "Returns an job object if a valid job ID was provided. Returns an error otherwise." } }, "summary": "Update a job", "tags": [ "Job" ] } }, "/api/v1/payment/sessions": { "post": { "description": "\nCreates a new payment session object.\n", "requestBody": { "content": { "application/json": { "schema": { "example": { "contractor": "cn_AbCdEfGh12", "return_url": "https://app.yourplatform.com/settings/billing/return" }, "properties": { "contractor": { "description": "The public ID of the contractor (e.g., `cn_AbCdEfGh12`). Must belong to your tenant. A contractor ID that does not belong to your tenant returns `404` to avoid leaking existence.", "type": "string" }, "return_url": { "description": "HTTPS URL the contractor will be redirected to when the flow terminates. The host must be in your organization's configured `hosted_flow_allowed_redirect_hosts` allowlist. Exact-match only; no wildcards, no suffix matching. URLs with credentials (`user:pass@`) or fragments are rejected.", "type": "string" } }, "required": [ "contractor", "return_url" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" } } }, "description": "Session created. The `url` field is shown exactly once and contains the single-use token the contractor must land on." }, "400": { "description": "Invalid input. `invalid_return_url` when the return URL fails scheme / host / allowlist validation. Ensure your organization has `hosted_flow_allowed_redirect_hosts` configured." }, "403": { "description": "Missing or invalid API key." }, "404": { "description": "Contractor not found. Returned when the contractor does not exist under your tenant." } }, "summary": "Create a payment session", "tags": [ "Payment Session" ] } }, "/api/v1/payment/sessions/{session}": { "get": { "description": "\nRetrieves the payment session with the given ID.\n", "parameters": [ { "description": "The public ID of the session (`hps_...`).", "in": "path", "name": "session_id", "required": true, "schema": { "example": "hps_xyz123", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" } } }, "description": "The current session object." }, "403": { "description": "Missing or invalid API key." }, "404": { "description": "Session not found. Returned when the id is unknown or belongs to another tenant." } }, "summary": "Retrieve a payment session", "tags": [ "Payment Session" ] } }, "/api/v1/payment/sessions/{session}/cancel": { "post": { "description": "\nCancels the payment session with the given ID. A session can\nonly be cancelled while it is still pending.\n", "parameters": [ { "description": "The public ID of the session to cancel.", "in": "path", "name": "session_id", "required": true, "schema": { "example": "hps_xyz123", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" } } }, "description": "Session cancelled. The webhook with `event_type: payment.session.cancelled` will follow asynchronously." }, "400": { "description": "`session_not_pending` — the session is already in a terminal state. `session_expired` — the session is past its `expires_at` and the expiry job hasn't flipped it yet." }, "403": { "description": "Missing or invalid API key." }, "404": { "description": "Session not found." } }, "summary": "Cancel a payment session", "tags": [ "Payment Session" ] } }, "/api/v1/policies": { "get": { "description": "\nReturns a list of policies you've previously created.\nThe policies are returned in sorted order, with the most\nrecent policies appearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination. `starting_after` is an policy ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `pl_fOo123`, your subsequent call can include `starting_after=pl_fOo123` in order to fetch the next page of the list.", "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for use in pagination. `ending_before` is an policy ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `pl_bAr123`, your subsequent call can include `ending_before=pl_bAr123` in order to fetch the previous page of the list.", "in": "query", "name": "ending_before", "required": false, "schema": { "type": "string" } }, { "description": "A filter to return policies by a specific quote ID.", "in": "query", "name": "quote", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Policy" }, "type": "array" } } }, "description": "An array of policies, up to limit. Each entry in the array is a separate policy object. If no more charges are available, the resulting array will be empty." } }, "summary": "List all policies", "tags": [ "Policy" ] }, "post": { "description": "\nCreates a new policy object.\n", "requestBody": { "content": { "application/json": { "schema": { "properties": { "effective_date": { "description": "A timestamp used to determine the insurance policy start date.", "type": "string" }, "expiration_date": { "description": "A timestemp used to determine the insurance policy end date.", "type": "string" }, "quote": { "description": "The ID of the quote used to create the policy.", "type": "string" } }, "required": [ "quote" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } }, "description": "Returns the policy object if the post succeeded." } }, "summary": "Create a policy", "tags": [ "Policy" ] } }, "/api/v1/policies/{policy}": { "delete": { "description": "\nPermanently deletes a policy. Deleting a policy immediately cancels\nthe insurance coverage for the contractor. Any assignments with an\neffective date after the policy deletion date will also be cancelled.\n", "parameters": [ { "description": "The ID of the desired policy (e.g., `pl_WzFRszJhoY`).", "in": "path", "name": "policy", "required": true, "schema": { "example": "pl_WzFRszJhoY", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "deleted": true, "deleted_at": 1640995200, "id": "pl_WzFRszJhoY", "object": "policy" }, "properties": { "deleted": { "type": "boolean" }, "deleted_at": { "description": "Unix timestamp (seconds since epoch) of when the policy was deleted.", "type": "integer" }, "id": { "description": "The policy ID.", "type": "string" }, "object": { "default": "policy", "type": "string" } } } } }, "description": "Returns an object with a deleted parameter on success. If the policy ID does not exist, this call returns an error." } }, "summary": "Delete a policy", "tags": [ "Policy" ] }, "get": { "description": "\nRetrieves the details of an existing policy.\nSupply the unique policy ID from either a policy\ncreation request or the policy list, and 1099Policy\nwill return the corresponding policy information.\n", "parameters": [ { "description": "The ID of the desired policy (e.g., `pl_WzFRszJhoY`).", "in": "path", "name": "policy", "required": true, "schema": { "example": "pl_WzFRszJhoY", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } }, "description": "Returns a policy object if a valid ID was provided." } }, "summary": "Retrieve a policy", "tags": [ "Policy" ] }, "put": { "description": "\nPolicies can be switched on and off using the is_active flag.\nUse this functionality if you don't have preset policy\nstart and end times.\n", "parameters": [ { "description": "The ID of the desired policy (e.g., `pl_WzFRszJhoY`).", "in": "path", "name": "policy", "required": true, "schema": { "example": "pl_WzFRszJhoY", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "is_active": false }, "schema": { "properties": { "is_active": { "description": "A flag to switch the policy on or off.", "type": "boolean" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } }, "description": "Returns the policy object if the update succeeded. Returns an error if update parameters are invalid." } }, "summary": "Update a policy", "tags": [ "Policy" ] } }, "/api/v1/quotes": { "get": { "description": "\nReturns a list of quotes you've previously created.\nThe quotes are returned in sorted order, with the most\nrecent quotes appearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination. `starting_after` is an quote ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `qt_fOo123`, your subsequent call can include `starting_after=qt_fOo123` in order to fetch the next page of the list.", "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for use in pagination. `ending_before` is an quote ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `qt_bAr123`, your subsequent call can include `ending_before=qt_bAr123` in order to fetch the previous page of the list.", "in": "query", "name": "ending_before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Quote" }, "type": "array" } } }, "description": "Returns an array of quote objects. If no more quotes are available, the resulting array will be empty." } }, "summary": "List all quotes", "tags": [ "Quote" ] }, "post": { "description": "\nTo provide insurance coverage to contractors on your platform, you\nfirst create a `Quote` object. If you use your test API keys,\neverything will occur as if in production but the policy that's\ngenerated will be a test policy.\n", "requestBody": { "content": { "application/json": { "schema": { "properties": { "bind": { "default": true, "description": "Controls how the request behaves when the contractor already has a matching policy for the requested coverage. When `true` (the default), the request is rejected with a `contractor_has_matching_policy` error. When `false`, the endpoint behaves like a \"get or create\" and instead returns the existing quote tied to the matching policy (with a `200` status), so you can surface its rates and fees—for example, to let a returning contractor opt in—without creating a duplicate. Defaults to `true`.", "type": "boolean" }, "contractor": { "description": "The ID of the contractor seeking a quote for insurance coverage.", "type": "string" }, "coverage_type": { "description": "An array of coverage types that can include one or more of the following insurance coverage values: `general`, `professional`, `workers-comp`, `media`, and `cyber`. Note that `media` and `cyber` coverage requires `general` coverage, except for Hawaii (HI) residents where general liability is not available.", "items": { "enum": [ "general", "professional", "workers-comp", "media", "cyber" ], "type": "string" }, "type": "array" }, "effective_date": { "description": "The date when the insurance coverage is set to take effect. Measured in seconds since the Unix epoch. This date must be set in the future. The default effective_date is the next day.", "format": "int64", "type": "integer" }, "end_date": { "description": "The date when the insurance coverage is set to expire. Measured in seconds since the Unix epoch. This date must be after the effective date. If the end_date is on the same day as the effective_date, it will automatically be adjusted to the start of the next day. The default end_date is 30 days after the effective date.", "format": "int64", "type": "integer" }, "job": { "description": "The ID of the job assignment that the contractor will be working on.", "type": "string" } }, "required": [ "job", "contractor", "coverage_type" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } }, "description": "Returned when `bind` is `false` and the contractor already has a matching policy. The body is the existing quote tied to that policy rather than a newly created one." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } }, "description": "Returns the quote object if the post succeeded." } }, "summary": "Create a quote", "tags": [ "Quote" ] } }, "/api/v1/quotes/{quote}": { "get": { "description": "\nRetrieves the details of a previously created quote. Supply the\nunique quote ID that was returned from your previous request,\nand 1099Policy will return the corresponding quote information.\n", "parameters": [ { "description": "The ID of the desired quote (e.g., `qt_5DciVga8Kt`).", "in": "path", "name": "quote", "required": true, "schema": { "example": "qt_5DciVga8Kt", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } }, "description": "Returns a quote object if a valid identifier was provided." } }, "summary": "Retrieve a quote", "tags": [ "Quote" ] }, "put": { "description": "\nQuotes that aren't bound to an issued policy are fully editable.\nOnce a policy is issued for a quote, the quote becomes uneditable.\n", "parameters": [ { "description": "The ID of the desired quote (e.g., `qt_5DciVga8Kt`).", "in": "path", "name": "quote", "required": true, "schema": { "example": "qt_5DciVga8Kt", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "contractor": "cn_Ehb3bYa", "coverage_type": [ "general", "workers-comp" ], "effective_date": 1646818364, "end_date": 1678334737, "job": "jb_jsb9KEcTpc" }, "properties": { "contractor": { "description": "The ID of the contractor seeking a quote for insurance coverage.", "type": "string" }, "coverage_type": { "description": "An array of coverage types that can include one or more of the following insurance coverage values: `general`, `professional`, `workers-comp`, `media`, and `cyber`.", "items": { "enum": [ "general", "professional", "workers-comp", "media", "cyber" ], "type": "string" }, "type": "array" }, "effective_date": { "description": "The date when the insurance coverage is set to take effect. Measured in seconds since the Unix epoch. This date must be set in the future. The default effective_date is the next day.", "format": "int64", "type": "integer" }, "end_date": { "description": "The date when the insurance coverage is set to expire. Measured in seconds since the Unix epoch. This date must be after the effective date. If the end_date is on the same day as the effective_date, it will automatically be adjusted to the start of the next day. The default end_date is 30 days after the effective date.", "format": "int64", "type": "integer" }, "job": { "description": "The ID of the job assignment that the contractor will be working on.", "type": "string" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } }, "description": "Returns the quote object if the update succeeded. Returns an error if update parameters are invalid." } }, "summary": "Update a quote", "tags": [ "Quote" ] } }, "/api/v1/webhook_endpoints": { "get": { "description": "\nReturns a list of your webhook endpoints. The webhook\nendpoints are returned sorted by updated date, with the\nmost recently updated webhook endpoints appearing first.\n", "parameters": [ { "description": "A limit on the number of objects to be returned. Limit can range between `1` and `100`, and the default is `10`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Webhook" }, "type": "array" } } }, "description": "Returns an array of webhook endpoint objects. If no more webhook endpoints are available, the resulting array will be empty." } }, "summary": "List all webhook endpoints", "tags": [ "Webhook Endpoint" ] }, "post": { "description": "\nCreates a new webhook endpoint object.\n", "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "A human-readable description of the webhook endpoint.", "type": "string" }, "events": { "description": "List of event types to subscribe to. If not provided, subscribes to all events. Use \"*\" to subscribe to all events. Available event types: `policy.active`, `policy.active.media`, `policy.cancelled`, `policy.reactivated`, `application.created`, `application.started`, `application.complete`, `application.expired`, `application.renewed`, `application.ineligible`, `application.manual_review`, `application.manual_review_approved`, `assignment.active`, `assignment.cancelled`, `certificate.flagged`, `certificate.approved`, `certificate.denied`, `invoice.charge_card_failed`, `invoice.charge_card_succeeded`, `category_code.added`", "example": [ "application.complete", "application.ineligible", "policy.active" ], "items": { "type": "string" }, "type": "array" }, "url": { "description": "The URL of the webhook endpoint.", "type": "string" } }, "required": [ "url" ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "Returns the webhook endpoint object if the post succeeded." } }, "summary": "Create a webhook endpoint", "tags": [ "Webhook Endpoint" ] } }, "/api/v1/webhook_endpoints/{webhook_endpoint}": { "delete": { "description": "\nDeletes the specified webhook endpoint.\n", "parameters": [ { "description": "The ID of the desired webhook endpoint.", "in": "path", "name": "webhook_endpoint", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "deleted": true, "deleted_at": 1640995200, "id": "whe_KPGc5vEZdvoETu39BNwu2Z", "object": "webhook_endpoint" }, "properties": { "deleted": { "type": "boolean" }, "deleted_at": { "description": "Unix timestamp (seconds since epoch) of when the webhook endpoint was deleted.", "type": "integer" }, "id": { "description": "The webhook endpoint ID.", "type": "string" }, "object": { "default": "webhook_endpoint", "type": "string" } } } } }, "description": "Returns a success message if a valid webhook endpoint ID was provided. Returns an error otherwise." } }, "summary": "Delete a webhook endpoint", "tags": [ "Webhook Endpoint" ] }, "get": { "description": "\nRetrieves the details of a webhook endpoint. You need only\nprovide the unique webhook endpoint ID.\n", "parameters": [ { "description": "The ID of the desired webhook endpoint (e.g., whe_KPGc5vEZdvoETu39BNwu2Z).", "in": "path", "name": "webhook_endpoint", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "Returns a webhook endpoint object if a valid ID was provided." } }, "summary": "Retrieve a webhook endpoint", "tags": [ "Webhook Endpoint" ] }, "put": { "description": "\nUpdates the specified webhook endpoint by setting\nthe values of the parameters passed. Any parameters\nnot provided will be left unchanged.\n", "parameters": [ { "description": "The ID of the desired webhook endpoint (e.g., `whe_KPGc5vEZdvoETu39BNwu2Z`).", "in": "path", "name": "webhook_endpoint", "required": true, "schema": { "example": "whe_KPGc5vEZdvoETu39BNwu2Z", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "A webhook endpoint for the example application.", "events": [ "application.complete", "application.ineligible", "policy.active" ], "url": "https://example.com/my/webhook/endpoint" }, "schema": { "properties": { "description": { "description": "A human-readable description of the webhook endpoint.", "type": "string" }, "events": { "description": "List of event types to subscribe to. If not provided, subscribes to all events. Use \"*\" to subscribe to all events. Available event types: `policy.active`, `policy.active.media`, `policy.cancelled`, `policy.reactivated`, `application.created`, `application.started`, `application.complete`, `application.expired`, `application.renewed`, `application.ineligible`, `application.manual_review`, `application.manual_review_approved`, `assignment.active`, `assignment.cancelled`, `certificate.flagged`, `certificate.approved`, `certificate.denied`, `invoice.charge_card_failed`, `invoice.charge_card_succeeded`, `category_code.added`", "example": [ "application.complete", "application.ineligible", "policy.active" ], "items": { "type": "string" }, "type": "array" }, "url": { "description": "The URL of the webhook endpoint.", "type": "string" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "Returns a webhook endpoint object if a valid webhook endpoint ID was provided. Returns an error otherwise." } }, "summary": "Update a webhook endpoint", "tags": [ "Webhook Endpoint" ] } } }, "servers": [ { "description": "Production server", "url": "https://api.1099policy.com" } ], "tags": [ { "description": "A `Contractor` object represents the contractor that can accept one or more jobs on your platform. The API allows you to create, delete, and update contractors. You can retrieve individual contractors as well as a list\n of all contractors.", "name": "Contractor" }, { "description": "The `Entity` object represents the contracting entity responsible for defining the job descriptions and for hiring contractors.\n\nThe API allows you to create, delete, and update entities. You can retrieve individual entities as well as a list of all entities.", "name": "Entity" }, { "description": "Store representations of the jobs on your platform in `Job` objects. The `Job` is used to, among other things, ensure that the insurance coverage that the 1099Policy platform issues correctly maps to the work that contractors will do.", "name": "Job" }, { "description": "The job category code object represents the pre-approved job category name and unique code that you receive when you onboard onto 1099Policy. Use this read-only endpoint to get your full list of the job category names and codes that your organization is pre-approved to use.", "name": "Category Code" }, { "description": "A `Certificate` object represents a Certificate of Insurance (COI) document that a contractor has provided to demonstrate they have their own insurance coverage. Use the Certificate API to upload, retrieve, and manage these documents as contractors bring their own insurance to your platform.\n\nWhen a contractor provides their own Certificate of Insurance, you can upload the PDF document using the Certificate API. The platform will automatically process the document and evaluate it against your organization's pre-defined insurance requirements. This evaluation is performed asynchronously, and you can retrieve the review results to determine whether the certificate satisfies your insurance requirements.\n\nThe Certificate API supports retrieving abbreviated review results that provide a summary of the evaluation, or expanded review results that include the full parsed certificate data and detailed audit results for each insurance requirement. Use the `expand` parameter to control the level of detail returned in the response.", "name": "Certificate" }, { "description": "The `Quote` object reflects whether a contractor is eligible for insurance and the premium owed for every $100 earned.", "name": "Quote" }, { "description": "A `Session` represents the independent contractor's session as they apply for insurance using the application wizard at apply.1099policy.com. You only need to create a `Session` for contractors that don't already have insurance coverage.\n\nOnce the contractor successfully completes their insurance application, the `Session` will contain a reference to the Contractor, the Job, and the active insurance Policy.\n\nYou can create a `Session` on your server and pass its ID to the client to begin the insurance application.", "name": "Session" }, { "description": "To procure contractor insurance, you create a `Policy` object. You can retrieve individual policies as well as list all policies. Policies are identified by a unique, random ID.\n\nImportant note: Creating a policy via the POST endpoint is an exception for most integrations. A policy object is created automatically when a contractor completes their insurance application (see Session API). Contact us if you plan to use the policy POST endpoint.", "name": "Policy" }, { "description": "To secure coverage for independent contractors that have previously had a policy issued through the 1099Policy platform, you create an `Assignment` object. \n\nIndependent contractors with an existing insurance policy procured using the 1099Policy platform have the option to receive per-job-assignment insurance coverage without having to complete additional insurance applications, provided certain eligibility criteria are met. \n\nYou can find the result of the eligibility check in the API response. Eligiblity is determined by parameters provided, including `job` and `contractor`. In particular, we look to see if the job `category_code` is the same as previously approved and time since the independent contractor completed their insurance application.\n\n1099Policy automatically charges the independent contractor's credit card on file, if a credit card exists. 1099Policy first notifies the contractor via email and then charges the contractor the premium amount due 24hrs later.", "name": "Assignment" }, { "description": "Invoices are statements of premium amounts owed by a contractor, based on the contractor's gross pay in the last pay period.\n\nThe invoice is used by 1099Policy to determine total funds to charge the contractor or to withdraw from the bank account you connect to the 1099Policy platform if your platform intends to withold insurance premium payments.", "name": "Invoice" }, { "description": "A payment session is a single-use, time-boxed flow that lets one of your contractors add or update their credit card on a secure page hosted by 1099Policy, then return to a URL you control. The contractor reaches the page via a one-time link that 1099Policy issues from your `POST` — the link expires and becomes invalid after the flow completes. Card data never touches your servers; tokenization happens client-side against our PCI-compliant payment provider.\n\nYou create a session on your server with the contractor's ID and a `return_url` of your choosing. We return a single-use URL that you redirect the contractor to. When they complete (or cancel) the flow, we redirect them back to your `return_url` and emit a signed `payment.session.completed` (or `.cancelled`, `.expired`) webhook event to the endpoint you have configured for 1099Policy webhooks.\n\nBefore using this endpoint, 1099Policy must have configured your organization's allowed `return_url` hostnames. Contact support to onboard.\n\nQuery parameters appended to the `return_url` on redirect (`hps_id`, `status`) are for your UX only and must not be the basis for any entitlement decision. The signed webhook is the source of truth for outcome.", "name": "Payment Session" }, { "description": "Webhooks are a way for 1099Policy to communicate with your server. To receive events you can use the `webhook_endpoints` API to register your webhook endpoints.\n\nIf you prefer, you can also register and configure your webhook endpoints from the [dashboard](https://dashboard.1099policy.com/webhooks).\n\nWhen an event occurs, we'll send an HTTP POST request to the registered webhook endpoint. We'll notify your server about events that happen in your 1099Policy account, such as when a contractor starts an insurance application or when a policy is issued.", "name": "Webhook Endpoint" }, { "description": "Events are how we communicate notable activity on an independent contractor's insurance application, policy, and certificate processing. When an event occurs, we create a new Event object. For example, when an insurance application is started, we create an `application.started` event; when a policy is issued, we create a `policy.active` event; and when a certificate evaluation completes, we create certificate events such as `certificate.approved`, `certificate.flagged`, or `certificate.denied`.\n\nAPI resource state changes trigger events. The state of that resource at the time of the change is embedded in the event's data field. For example, an `application.started` event will contain an insurance application `Session` object, a `policy.active` event will contain a `Policy` object, and certificate events will contain a `Certificate` object with the evaluation results.\n\nThese events are sent to your registered webhook endpoint, allowing you to respond immediately when certificate processing completes without needing to poll the API.\n\nUse the events endpoints to retrieve an individual event or a list of events. You can listen for events by registering your server endpoint via the 1099Policy [dashboard](https://dashboard.1099policy.com/webhooks). Our webhooks system send the Event objects directly to your registered endpoint.", "name": "Event" } ], "x-tagGroups": [ { "name": "Core Resources", "tags": [ "Contractor", "Entity", "Job", "Category Code", "Certificate", "Event" ] }, { "name": "Insurance", "tags": [ "Quote", "Session", "Policy", "Assignment" ] }, { "name": "Billing", "tags": [ "Invoice", "Payment Session" ] }, { "name": "Webhooks", "tags": [ "Webhook Endpoint", "Event" ] } ], "x-topics": [ { "content": "To use the 1099Policy API you need to authenticate requests using API keys. Sign up for a developer account to view and manage your API keys from the 1099Policy Dashboard. [https://dashboard.1099policy.com/signup](https://dashboard.1099policy.com/signup)\n\nYour API tokens should be guarded closely. As a reminder, do not share your secret API keys in publicly accessible areas such as GitHub or client-side code, for example. Instead use environment variables, web server settings, startup script, or a configuration file that is excluded from your version control.\n\nTest mode secret keys have the prefix `t9k_test_` and live mode secret keys have the prefix `t9k_live_`.\n\nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.", "example": "```curl\n curl \\\n -X GET https://api.1099policy.com/api/v1/contractors \\\n -H \"Authorization: Basic t9k_test_wvnsjtZ8aMlbfGbIm0Lc0\"\n```", "title": "Authentication" }, { "content": "Clients can make requests to either the `sandbox` or `production` environment by using the header `Ten99Policy-Environment` and specifying either `sandbox` or `production`. The default is `sandbox`.", "example": "```curl\n curl \\\n -X GET https://api.1099policy.com/api/v1/contractors \\\n -H \"Authorization: Basic t9k_test_wvnsjtZ8aMlbfGbIm0Lc0\" \\\n -H \"Ten99Policy-Environment: production\"\n```", "title": "Environment" }, { "content": "1099Policy uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error due to the the information provided (e.g., a required parameter was omitted, a create policy request failed, etc.). Codes in the 5xx range indicate an error with 1099Policy's servers (these are rare).\n\nSome `4xx` errors that could be handled programmatically (e.g., contractor ineligible for coverage) include an error code that briefly explains the error reported.\n\n# Handling Errors\n\nOur API libraries raise exceptions for many reasons, such as a failed create policy request, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.", "example": "```basic \n 200 (OK) Everything worked as expected.\n 400 (Bad Request) Check for a missing required parameter.\n 401 (Unauthorized) No valid API key provided.\n 403 (Forbidden) Confirm API key has permissions to make request.\n 404 (Not Found) The requested resource doesn't exist.\n 429 (Too Many Requests) Too many requests to the API too quickly.\n 500 (Server Error) Something went wrong on 1099Policy's end.\n```", "title": "Errors" }, { "content": "The 1099Policy API checks every request header for an an additional `Ten99Policy-Idempotent-Key`. We use this field to perform an idempotency check to avoid duplicate transfers in case of network failures or timeouts. For example, if a request to create a contractor fails to return a response due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one contractor is created.\n\n1099Policy's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including `500` errors.\n\nWe suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.\n\nKeys expire after 24 hours, so a new request is generated if a key is reused outside of that time frame. Results are only saved if an API endpoint started executing. You can safely retry requests that fail validation or conflicts with another request that was executing concurrently. \n\nAll `POST` requests accept idempotency keys. Sending idempotency keys in `GET` and `DELETE` requests has no effect and should be avoided, as these requests are idempotent by definition.", "example": "```curl\n curl \\\n -X POST https://api.1099policy.com/api/v1/jobs \\\n -u t9k_test_wvnsjtZ8aMlbfGbIm0Lc0: \\\n -H \"Ten99Policy-Idempotent-Key: d9YozBtG5R\" \\\n -H 'Content-Type: application/json' \\\n -d ...\n```", "title": "Idempotent Requests" }, { "content": "All dates and timestamps in the 1099Policy API are represented as Unix timestamps \n(integers) and are always in UTC (Coordinated Universal Time). When sending date \nvalues in API requests, provide them as Unix timestamps representing UTC time.\n\n\n## Date Format\n\n\nDates are represented as Unix timestamps (seconds since January 1, 1970 UTC). \nFor example, `1705312800` represents January 15, 2024 at 10:00:00 AM UTC.\n\n\n## Same-Day Date Handling\n\n\nWhen creating quotes or assignments, if the `end_date` and `effective_date` are \non the same day, the API automatically adjusts the `end_date` to the start of the \nnext day (midnight UTC). This ensures proper date range validation and prevents \nsame-day date conflicts.\n\n\n## Date Validation Rules\n\n\n- `effective_date` must be in the future (with a small grace period for clock skew)\n- `end_date` must be after `effective_date`\n- `end_date` must be within one year of `effective_date`\n- Both dates are validated and normalized to UTC before processing\n\n\nWhen working with dates in your application, ensure you convert local times to \nUTC before sending timestamps to the API. All date comparisons and validations \nperformed by the API use UTC.", "example": "```basic\n\n{\n \"effective_date\": 1705312800,\n \"end_date\": 1705338000\n}\n\n```\n\n\nIn the example above, both dates are on the same day (January 15, 2024), so the \nAPI will automatically adjust `end_date` to January 16, 2024 00:00:00 UTC.", "title": "Date Handling" } ] } ```