--- 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: 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: review_results: 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: review_results: 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: stamping_fee: 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: 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: 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. A 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: 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. The 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. API 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. Use 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. The 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. A 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. A 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. By 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. When a wage change re-prices an invoice, the replacement invoice keeps this value rather than re-inheriting it from the job. Precedence: 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. Job category codes are pre-approved by 1099Policy so you can offer contractors insurance to new jobs on your platform in real time. To 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. The `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. A 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. A 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. Important 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. Important 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. A 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. A 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: stamping_fee: 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. A 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. Once 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. You 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. If you prefer, you can also register and configure your webhook endpoints from the [dashboard](https://dashboard.1099policy.com/webhooks). When 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](https://1099policy.com/docs/automating-compliance#webhook-signature-verification). 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. Use 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: |2 Returns a list of insurance application Sessions. 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: |2 Creates a session object. 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: |2 Retrieves the insurance application session with the given ID. 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: |2+ Updates the success_url and cancel_url of a specified session. If either parameters is not provided it will be left unchanged. 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: |2 Expires the insurance application session with the given ID. An insurance application session can't be expired if the application status is complete. After it expires, a contractor can’t complete an insurance application session and contractors loading the insurance application session see a message saying the insurance application session is expired. 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: |2 Returns a list of your assignments. The assigments returned are sorted by creation date, with the most recently created assignments appearing first. 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: |2 This endpoint creates an assignment object that you can use to attach insurance coverage to any job assignment a contractor takes after the contractor has gone active on the 1099Policy platform (i.e., after completing thier insurance application successfully). 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: |2 Cancels an existing assignment based on the provided job ID. If you attempt to cancel an assignment after it has started, the request will fail. If you need the option to cancel an assignment after its start date, please contact us. 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/extend": post: description: |2 Extends an existing assignment based on the provided job ID. Sets a new end date for bound coverage. If you attempt to extend after coverage has ended, or the end date is invalid, the request will fail. Updating ``end_date`` on a bound assignment via ``PUT`` is not supported; use this endpoint instead. **Certificate of Insurance (COI) regeneration**: When extending coverage, COI PDFs are regenerated asynchronously to reflect the new end date. The response returns immediately with ``certificate_refresh_pending: true``, indicating that: - The ``certificate`` URLs in the response point to the old PDFs (pre-regeneration) - Fresh certificate URLs will be included in the ``assignment.extended`` webhook, which is published after COI regeneration completes - Fresh URLs can also be fetched via the API after background processing finishes This async design ensures the API responds quickly without blocking for PDF generation. 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: |2 Retrieves all media coverage records associated with a policy. 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: |2 Creates a new media coverage record for a policy and adds published content. The media coverage record is used to track content published by contractors and generate Certificates of Insurance (COIs) for media coverage. 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: |2 Permanently deletes an assignment. This cannot be undone. Attempts to delete assignments with jobs that have invoices paid in full will fail. 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: |2 Retrieves the assignment with the given ID. 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: |2 Assignments are editable up until the related invoice is paid in full. 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: |2 Returns a list of your approved job category codes. The job category codes are returned sorted by approval date, with the most recently approved job categories appearing first. 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: |2 Returns a list of your contractors. The contractors are returned sorted by creation date, with the most recent contractors appearing first. 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: |2 Creates a new contractor object. 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: |2 Permanently deletes a contractor. It cannot be undone. Also immediately cancels any active policies connected with the contractor. 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: |2 Retrieves the details of an existing contractor. You need only supply the unique contractor identifier that was returned upon contractor creation. 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: |2 Updates the specified contractor by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts mostly the same arguments as the contractor creation call. 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: |2 Generates a secure, time-limited login URL for contractor portal access. This allows agencies to provide direct portal access without requiring contractors to go through email verification. 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: Token expiration timestamp (ISO 8601) example: '2025-12-12T16:00:00Z' format: date-time type: string 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: |2 Returns a list of policies for a given contractor. 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: |2 Returns a list of your contracting entities. The entities are returned sorted by creation date, with the most recent entities appearing first. 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: |2 Creates a new contracting entity object. 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: |2 Permanently deletes an entity. It cannot be undone. Also immediately cancels any insurance policies connected with active jobs managed by the entity. 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: |2 Retrieves the details of an existing entity. You need only supply the unique entity ID that was returned upon entity creation. 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: |2 Updates the specified entity by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts mostly the same arguments as the entity creation call. 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: |2 Returns a list of events with pagination (20 events per page). The events are sorted by creation date, with the most recent event appearing first. 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: |2 Retrieves the details of an event. You need only provide the unique event ID which you would have received in a webhook. 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: |2+ Returns a list of certificates. The certificates are returned sorted by creation date, with the most recently created certificates appearing first. Supports pagination using `starting_after` and `ending_before`. 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`. ' 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. ' 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. ' 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. ' 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. ' summary: List all certificates. tags: - Certificate post: description: |2+ Uploads a new Certificate of Insurance (COI) PDF file, validates it, and creates a certificate record. The certificate processing is performed asynchronously in the background. The initial response indicates that the certificate has been accepted for processing with a status of "pending". **Asynchronous Processing:** After uploading a certificate, the platform automatically processes the document and evaluates it against your organization's pre-defined insurance requirements. This evaluation happens asynchronously, so the initial response will have: - `status`: "pending" (indicating processing has not yet started) - `review_results`: `null` (will be populated once processing completes) **Monitoring Certificate Status:** You can monitor the certificate status in two ways: 1. **Polling**: Periodically retrieve the certificate using the GET endpoint to check the `status` field. The status will transition from "pending" → "processing" → ("approved" | "flagged" | "denied" | "error") as processing completes. 2. **Webhooks**: Register a webhook endpoint to receive real-time notifications when processing completes. The following events are sent: - `certificate.approved` - Certificate passed all requirements - `certificate.flagged` - Certificate failed some requirements - `certificate.denied` - Certificate was denied **Retrieving Review Results:** Once processing is complete, use the `expand[]=review_results` parameter when retrieving the certificate to get abbreviated review results, or `expand[]=review_results.full` for complete details including parsed certificate data and detailed audit results. 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. ' summary: Create a new certificate. tags: - Certificate "/api/v1/files/certificates/{certificate}": delete: description: |2+ Deletes an existing certificate by its ID. 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. ' summary: Delete a certificate. tags: - Certificate get: description: |2+ Retrieves the details of an existing certificate by its ID. Use this endpoint to poll for certificate status updates during asynchronous processing. **Certificate Status Lifecycle:** The certificate status transitions through the following states: - `pending` - Certificate has been uploaded but processing has not started - `processing` - Certificate is currently being processed - `approved` - Certificate passed all insurance requirements - `flagged` - Certificate failed some requirements (may require manual review) - `denied` - Certificate was denied - `error` - An error occurred during processing **Retrieving Review Results:** Once processing is complete, use the `expand` parameter to retrieve review results: - `expand[]=review_results` - Returns abbreviated results with summary counts - `expand[]=review_results.full` - Returns full parsed certificate data and detailed audit results for each insurance requirement 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. ' 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. ' '404': description: Certificate not found summary: Retrieve a certificate. tags: - Certificate "/api/v1/invoices": get: description: |2 You can list all invoices, or list the invoices for a specific contractor. The invoices are returned sorted by creation date, with the most recently created invoices appearing first. 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: |2 This endpoint creates an invoice that reflects the insurance premium owed by the contractor for the specified pay period. 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. By 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. If 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: |2 Permanently deletes an invoice. This cannot be undone. Attempts to delete invoices that have been paid will fail. 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: |2 Retrieves the invoice with the given ID. 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: |2 Invoices that haven't been paid are fully editable. Once an invoice is paid, it becomes uneditable. 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. Provide 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: |2 Returns a list of your jobs. The jobs are returned sorted by creation date, with the most recently created jobs appearing first. 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: |2 Creates a new job object. Used to classify the work that 1099Policy applies to insure the contractor. 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. Job category codes are pre-approved by 1099Policy so you can offer contractors insurance to new jobs on your platform in real time. To 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. The `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: |2 Delete a job. Deleting a job is only possible if it has no insurance policies associated with it. 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: |2 Retrieves the details of an existing job. Supply the unique job ID from either a job creation request or the job list, and 1099Policy will return the corresponding job information. 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: |2 Updates the specific job by setting the values of the parameters passed. Any parameters not provided will be left unchanged. 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. The `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: |2 Creates a new payment session object. 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: |2 Retrieves the payment session with the given ID. 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: |2 Cancels the payment session with the given ID. A session can only be cancelled while it is still pending. 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: |2 Returns a list of policies you've previously created. The policies are returned in sorted order, with the most recent policies appearing first. 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: |2 Creates a new policy object. 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: |2 Permanently deletes a policy. Deleting a policy immediately cancels the insurance coverage for the contractor. Any assignments with an effective date after the policy deletion date will also be cancelled. 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: |2 Retrieves the details of an existing policy. Supply the unique policy ID from either a policy creation request or the policy list, and 1099Policy will return the corresponding policy information. 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: |2 Policies can be switched on and off using the is_active flag. Use this functionality if you don't have preset policy start and end times. 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: |2 Returns a list of quotes you've previously created. The quotes are returned in sorted order, with the most recent quotes appearing first. 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: |2 To provide insurance coverage to contractors on your platform, you first create a `Quote` object. If you use your test API keys, everything will occur as if in production but the policy that's generated will be a test policy. requestBody: content: application/json: schema: 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`. 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: '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: |2 Retrieves the details of a previously created quote. Supply the unique quote ID that was returned from your previous request, and 1099Policy will return the corresponding quote information. 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: |2 Quotes that aren't bound to an issued policy are fully editable. Once a policy is issued for a quote, the quote becomes uneditable. 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: |2 Returns a list of your webhook endpoints. The webhook endpoints are returned sorted by updated date, with the most recently updated webhook endpoints appearing first. 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: |2 Creates a new webhook endpoint object. 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: |2 Deletes the specified webhook endpoint. 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: |2 Retrieves the details of a webhook endpoint. You need only provide the unique webhook endpoint ID. 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: |2 Updates the specified webhook endpoint by setting the values of the parameters passed. Any parameters not provided will be left unchanged. 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 of all contractors. name: Contractor - description: |- The `Entity` object represents the contracting entity responsible for defining the job descriptions and for hiring contractors. The 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. When 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. The 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. Once the contractor successfully completes their insurance application, the `Session` will contain a reference to the Contractor, the Job, and the active insurance Policy. You 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. Important 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. The 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. You 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. Before using this endpoint, 1099Policy must have configured your organization's allowed `return_url` hostnames. Contact support to onboard. Query 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. If you prefer, you can also register and configure your webhook endpoints from the [dashboard](https://dashboard.1099policy.com/webhooks). When 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`. API 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. These events are sent to your registered webhook endpoint, allowing you to respond immediately when certificate processing completes without needing to poll the API. Use 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) Your 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. Test mode secret keys have the prefix `t9k_test_` and live mode secret keys have the prefix `t9k_live_`. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. example: |- ```curl curl \ -X GET https://api.1099policy.com/api/v1/contractors \ -H "Authorization: Basic t9k_test_wvnsjtZ8aMlbfGbIm0Lc0" ``` 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 curl \ -X GET https://api.1099policy.com/api/v1/contractors \ -H "Authorization: Basic t9k_test_wvnsjtZ8aMlbfGbIm0Lc0" \ -H "Ten99Policy-Environment: production" ``` 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). Some `4xx` errors that could be handled programmatically (e.g., contractor ineligible for coverage) include an error code that briefly explains the error reported. # Handling Errors Our 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 curl \ -X POST https://api.1099policy.com/api/v1/jobs \ -u t9k_test_wvnsjtZ8aMlbfGbIm0Lc0: \ -H "Ten99Policy-Idempotent-Key: d9YozBtG5R" \ -H 'Content-Type: application/json' \ -d ... ``` 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