Create a new certificate.

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.

Servers

• Production server: https://api.1099policy.com (Production server)

Parameters

Body: multipart/form-data (object)

• certificate (string(binary)) The certificate PDF file to be uploaded (max 15MB).

• contractor (string) The ID of the contractor associated with the certificate.

Responses

201

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.

Body: application/json (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.

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

• updated (integer(int64)) Time at which the certificate was last updated.