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