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)
• A contractor record to associate the certificate with

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

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:

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

Response:

{
  "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:

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

See Using Webhooks 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:

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

Response:

{
  "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:

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

See Working with Review Results for details on interpreting the full response.

What's next?

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