Basic upload

Submit a COI PDF associated with a contractor:

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 queued for processing. You'll receive a webhook when evaluation completes.

File requirements

Format validation

The system validates PDF files at three levels:

• File extension must be .pdf
• MIME type must be application/pdf
• File must begin with valid PDF magic bytes (%PDF)

Other formats (images, Word documents, scanned TIFFs) are rejected.

Page limit

Only the first 2 pages of each PDF are sent to the AI for analysis. Ensure all critical coverage information—limits, expiration dates, certificate holder, additional insureds—appears on these pages.

Contractor association

Every certificate must be associated with a contractor. The contractor record must exist before uploading:

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

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

The contractor association determines:

• Which insurance requirement is used (based on the contractor's entity, if applicable)
• Where the certificate appears in your Dashboard
• How insured name validation works (contractor's name or company must match)

Multiple certificates per contractor

Contractors can have multiple certificates. Each upload creates an independent record with its own evaluation results.

Common scenarios:

Finding the latest approved certificate

import requests

response = requests.get(
    'https://api.1099policy.com/api/v1/files/certificates',
    auth=('YOUR_SECRET_KEY', ''),
    params={'contractor': 'cn_abc123'}
)
certificates = response.json()['data']

# Filter to approved certificates
approved = [c for c in certificates if c['status'] == 'approved']

# Get most recent
if approved:
    latest = max(approved, key=lambda x: x['created'])

Re-uploading after errors

If a certificate ends up in error status, you can upload a new one. Common reasons to re-upload:

There's no "retry" endpoint—simply upload the corrected PDF as a new certificate:

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

The original errored certificate remains in your records for reference.

What happens after upload

1. Immediate response — You receive the certificate object with status: "pending"
2. Processing begins — AI parses the PDF and extracts coverage data (typically 1-2 minutes)
3. Evaluation runs — Extracted data is checked against the applicable insurance requirement
4. Webhook sent — You receive certificate.approved, certificate.flagged, or certificate.denied
5. Results available — Fetch detailed results using the expand parameter

See Working with Review Results for how to interpret the evaluation output.

Deleting certificates

To remove a certificate:

curl -X DELETE https://api.1099policy.com/api/v1/files/certificates/ci_YnsHeB9PTo \
  -u YOUR_SECRET_KEY:

Next: Learn how to work with review results to understand evaluation outcomes.