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


[Powered by Bump.sh](https://bump.sh)