Create a new certificate.

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.1099policy.com/mcp

Standard setup for AI tools providing an mcp.json file

{
  "1099Policy MCP server": {
    "url": "https://docs.1099policy.com/mcp"
  }
}

POST /api/v1/files/certificates

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:

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

Submitting certificate data instead of a file:

When the certificate was read somewhere you cannot forward the file from (an AI assistant looking at a screenshot, for example), send application/json with the fields read off the certificate as certificate — the same shape review_results.full returns as parsed_certificate_json. The record is created with source "assistant" and no pdf_url, and is reviewed against the same insurance requirements. Check the data first with POST /files/certificates/evaluate, which reviews without creating anything.

Body

certificate object Required

The fields read off the certificate: insured, certificate_holder, authorized_representative_signature_present, description_of_operations and coverages keyed by coverage type (commercial_general_liability, automobile_liability, excess_umbrella_liability, workers_compensation, professional_liability, cyber_liability, criminal_liability, liquor_liability), each with insurer_letter, policy_number_string, policy_effective_date, policy_expiration_date (MM/DD/YYYY), addl_insd, subr_wvd and limits.
contractor string Required

The ID of the contractor associated with the certificate.
entity string

Optional. Review against the requirement tied to this entity (en_…).
filename string

Optional. A name for the record, e.g. the dropped file's name.
insurance_requirement string

Optional. Review against this requirement (ir_…) instead of the default one.
user_provided array[string]

Optional. Field paths a person supplied rather than the document, e.g. coverages.workers_compensation.policy_expiration_date.

Body

certificate string(binary) Required

The certificate PDF file to be uploaded (max 15MB).
contractor string Required

The ID of the contractor associated with the certificate.

Responses

201 application/json

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.
Hide response attributes Show response attributes object
- contractor string
  
  The ID of the contractor associated with this certificate.
- created integer(int64)
  
  Time at which the certificate was uploaded.
- filename string
  
  The original filename of the uploaded PDF.
- id string
  
  Unique identifier for the certificate.
- pdf_url string | null
  
  URL to access the certificate PDF. This will be null until the certificate has been processed and stored.
- review_results object | null
  
  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.
  
  Hide review_results attributes Show review_results attributes object | null
  
  audit_results array[object]
  
  Detailed results for each insurance requirement evaluation (expanded format only).
  
  Hide audit_results attributes Show audit_results attributes object
  
  created integer
  
  Timestamp when this result was created.
  
  id string
  
  manually_approved boolean
  
  Whether this result was manually approved.
  
  message string
  
  Human-readable message about the evaluation result.
  
  result string
  
  Whether this requirement passed or failed.
  
  Values are pass or fail.
  
  rule_name string
  
  Human-readable name of the rule.
  
  rule_path string
  
  The path to the rule being evaluated.
  
  created integer
  
  Timestamp when the audit was created.
  
  id string
  
  The ID of the certificate audit.
  
  parsed_certificate_json object
  
  Full parsed certificate data extracted from the PDF (expanded format only). Contains structured data including coverages, limits, dates, and parties.
  
  status string
  
  The final evaluation status.
  
  Values are pending, processing, approved, flagged, denied, or error.
  
  summary object
  
  Summary of rule evaluation (abbreviated format only).
  
  Hide summary attributes Show summary attributes object
  
  failed integer
  
  Number of requirements that failed.
  
  passed integer
  
  Number of requirements that passed.
  
  total_rules integer
  
  Total number of insurance requirements evaluated.
  
  updated integer
  
  Timestamp when the audit was last updated.
- status string
  
  The current processing status of the certificate. Status transitions: pending → processing → (approved | flagged | denied | error). Use polling or webhooks to monitor status changes.
  
  Values are pending, processing, approved, flagged, denied, or error.
- updated integer(int64)
  
  Time at which the certificate was last updated.

POST /api/v1/files/certificates

curl \
 --request POST 'https://api.1099policy.com/api/v1/files/certificates' \
 --header "Content-Type: application/json" \
 --data '{
  "certificate": {},
  "contractor": "string",
  "entity": "string",
  "filename": "string",
  "insurance_requirement": "string",
  "user_provided": [
    "string"
  ]
}'

curl \
 --request POST 'https://api.1099policy.com/api/v1/files/certificates' \
 --header "Content-Type: multipart/form-data" \
 --form "certificate=@file" \
 --form "contractor=string"

Request examples

{
  "certificate": {},
  "contractor": "string",
  "entity": "string",
  "filename": "string",
  "insurance_requirement": "string",
  "user_provided": [
    "string"
  ]
}

Response examples (201)

{
  "contractor": "cn_xyz789",
  "created": 1646818364,
  "filename": "certificate_of_insurance.pdf",
  "id": "ci_abc123",
  "pdf_url": "https://storage.example.com/certificates/ci_abc123.pdf",
  "review_results": {
    "audit_results": [
      {
        "created": 42,
        "id": "car_result123",
        "manually_approved": true,
        "message": "string",
        "result": "pass",
        "rule_name": "CGL Limits",
        "rule_path": "coverages.commercial_general_liability.limits"
      }
    ],
    "created": 42,
    "id": "ca_audit123",
    "parsed_certificate_json": {},
    "status": "pending",
    "summary": {
      "failed": 0,
      "passed": 5,
      "total_rules": 5
    },
    "updated": 42
  },
  "status": "pending",
  "updated": 1646818364
}