# Getting Started

Upload your first Certificate of Insurance and retrieve the review results in minutes.

## Prerequisites

Before you begin, make sure you have:

- [ ] An API key (find this in your Dashboard under **Settings → API Keys**)
- [ ] At least one insurance requirement configured (see [Configuring Insurance Requirements](/content/docs/getting-started-with-automated-certificate-review#/index.html))
- [ ] A contractor record to associate the certificate with

If you don't have a contractor yet, create one:

```bash
curl https://api.1099policy.com/api/v1/contractors \
  -u YOUR_SECRET_KEY: \
  -d email="contractor@example.com" \
  -d first_name="Jane" \
  -d last_name="Smith"
```

Save the returned `id` (e.g., `cn_abc123`) — you'll need it in the next step.

## Step 1: Upload a certificate

Submit a COI PDF for review:

```bash
curl https://api.1099policy.com/api/v1/files/certificates \
  -u YOUR_SECRET_KEY: \
  -F "contractor=cn_abc123" \
  -F "certificate=@/path/to/certificate.pdf"
```

Response:

```json
{
  "id": "ci_YnsHeB9PTo",
  "contractor": "cn_abc123",
  "status": "pending",
  "created": 1760509809,
  "filename": "certificate.pdf",
  "review_results": null
}
```

The certificate is now queued for processing. Save the `id` to retrieve results later.

**File requirements**  
PDF only, maximum 15 MB. Only the first 2 pages are analyzed.

## Step 2: Wait for the webhook

When processing completes, we send a webhook event to your registered endpoint. Processing typically completes within 1-2 minutes.

You'll receive one of these events:

- `certificate.approved` — All requirements passed
- `certificate.flagged` — Some requirements failed
- `certificate.denied` — Critical requirements failed

Example webhook payload:

```json
{
  "id": "evt_abc123",
  "type": "certificate.approved",
  "created": 1760509813,
  "data": {
    "object": {
      "id": "ci_YnsHeB9PTo",
      "contractor": "cn_abc123",
      "status": "approved",
      "created": 1760509809
    }
  }
}
```

See [Using Webhooks](/content/docs/getting-started-with-automated-certificate-review#/index.html) for setup instructions and signature verification.

**Testing without webhooks**  
You can poll `GET /api/v1/files/certificates/{id}` until `status` is no longer `pending` or `processing`.

## Step 3: Retrieve review results

Once you receive the webhook (or confirm processing is complete), fetch the results using the `expand` parameter:

```bash
curl "https://api.1099policy.com/api/v1/files/certificates/ci_YnsHeB9PTo?expand[]=review_results" \
  -u YOUR_SECRET_KEY:
```

Response:

```json
{
  "id": "ci_YnsHeB9PTo",
  "contractor": "cn_abc123",
  "status": "flagged",
  "review_results": {
    "id": "ca_xyz789",
    "status": "flagged",
    "summary": {
      "total_rules": 8,
      "passed": 6,
      "failed": 2
    },
    "created": 1760509813
  }
}
```

This tells you the certificate failed 2 of 8 requirements. To see exactly which rules failed, request the full results:

```bash
curl "https://api.1099policy.com/api/v1/files/certificates/ci_YnsHeB9PTo?expand[]=review_results.full" \
  -u YOUR_SECRET_KEY:
```

See [Working with Review Results](/content/docs/getting-started-with-automated-certificate-review#/index.html) for details on interpreting the full response.

## What's next?

You've successfully uploaded a certificate and retrieved results. From here:

| Goal | Guide |
| --- | --- |
| Configure what coverage rules to check | [Configuring Insurance Requirements](/content/docs/getting-started-with-automated-certificate-review#/index.html) |
| Handle different certificate statuses in your app | [Working with Review Results](/content/docs/getting-started-with-automated-certificate-review#/index.html) |
| Set up webhooks for real-time notifications | [Using Webhooks](/content/docs/getting-started-with-automated-certificate-review#/index.html) |
| Understand file limits, timeouts, and error handling | [Edge Cases & Troubleshooting](/content/docs/getting-started-with-automated-certificate-review#/index.html) |