Retrieve a certificate.

View as markdown
GET /api/v1/files/certificates/{certificate}

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

Path parameters

  • certificate string Required

    The ID of the desired certificate.

Query parameters

  • expand array[string]

    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.

Responses

  • 200 application/json

    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.

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

    Certificate not found

GET /api/v1/files/certificates/{certificate} 
curl \
 --request GET 'https://api.1099policy.com/api/v1/files/certificates/ci_YnsHeB9PTo'
Response examples (200) 
{
  "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
}