Create a new certificate.

View as Markdown
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:

  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.

multipart/form-data

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: multipart/form-data" \
 --form "certificate=@file" \
 --form "contractor=string"
Response examples (201) 
{
  "contractor": "cn_xyz789",
  "created": 1646818364,
  "filename": "certificate_of_insurance.pdf",
  "id": "string",
  "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
}