Integration scope and objectives

This guide describes Summit’s developer interface for exchanging proof‑of‑insurance and policy status with property technology and management systems used in Canada. It covers data models, platform field mappings, secure policy uploads, signed status webhooks, retry semantics, and operational SLAs. For privacy and data handling, see Summit’s Privacy Policy.

Authentication and security

• API authentication: OAuth 2.0 client credentials (machine-to-machine). Obtain client_id and client_secret from your Summit account team.

• Transport security: TLS 1.2+ required. Reject plaintext (HTTP) requests.

• Request signing (webhooks): Summit signs every webhook with an HMAC-SHA256 signature using a shared secret. Header: X-Summit-Signature: t={unix_ts},v1={hex_hmac}. Compute HMAC over "{timestamp}.{raw_body}".

• Replay protection: Verify the timestamp t is within 5 minutes of receipt and ensure a one-time nonce or delivery_id has not been processed before.

• Idempotency: Provide Idempotency-Key on POST/PUT. Summit treats identical keys within 24 hours as duplicates and returns the original response.

• Data minimization: Send only fields required to issue, verify, or track insurance certificates. PHI and banking details are not accepted. See privacy commitments in the Privacy Policy.

Data model for property COI exchange

Core objects exchanged between Summit and property systems:

• Policy: policy_number, insurer_name, policy_type (CGL, Property, E&O, D&O, Cyber), effective_date, expiry_date, limits (per_occurrence, aggregate), endorsements, cancellation_notice_days, broker (name, phone, email), documents (COI PDF, endorsements).

• CertificateHolder: name, address, email, contact_phone, reference_ids (property_id, unit_id, lease_id, tenant_id), additional_insured (boolean), waiver_of_subrogation (boolean).

• Status: submitted, verified, lapsed, reinstated; includes reason_code, reason_detail, observed_at, actor (carrier, broker, system), evidence (doc_ids, checksums).

Field mapping to common property systems

The exact field names can vary by tenant and version; the following mapping reflects commonly available fields. Use your platform’s custom fields where needed.

Policy upload API (asynchronous)

• Endpoint: POST {BASE_URL}/v1/policies

• Auth: Bearer access_token from OAuth 2.0 client credentials

• Idempotency: Provide Idempotency-Key

• Response: 202 Accepted with job_id; poll or await webhook

Example curl (replace placeholders):

# 1) Get token

curl -s -X POST \
 "{AUTH_URL}/oauth2/token" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&scope=policies:write policies:read webhooks:read"

# 2) Upload policy + COI

curl -X POST "{BASE_URL}/v1/policies" \
 -H "Authorization: Bearer {ACCESS_TOKEN}" \
 -H "Idempotency-Key: {UUIDv4}" \
 -H "Content-Type: application/json" \
 -d '{
 "policy": {
 "policy_number": "ABC123456",
 "insurer_name": "Example Insurance Company of Canada",
 "policy_type": "CGL",
 "effective_date": "2025-01-01",
 "expiry_date": "2026-01-01",
 "limits": {"per_occurrence": 2000000, "aggregate": 5000000},
 "cancellation_notice_days": 30,
 "endorsements": ["Additional Insured", "Waiver of Subrogation"]
 },
 "certificate_holder": {
 "name": "ABC Apartments",
 "address": "123 Main St, Kelowna, BC V1Y 1A1",
 "additional_insured": true,
 "waiver_of_subrogation": true,
 "reference_ids": {
 "property_id": "KEL-001",
 "unit_id": "Unit-204",
 "lease_id": "L-7788",
 "tenant_id": "RES-9981"
 }
 },
 "documents": {
 "coi_pdf": {"content_type": "application/pdf", "base64": "{BASE64_PDF}"}
 }
 }'

202 response:

{
 "job_id": "job_01HFQ0...",
 "status": "accepted",
 "links": {"self": "/v1/jobs/job_01HFQ0..."}
}

Status webhooks (submitted, verified, lapsed, reinstated)

• Configure your endpoint in Summit Console. Provide one HTTPS URL per environment.

• Delivery: At‑least‑once. Expect retries with exponential backoff and jitter (see below). Use delivery_id and Idempotency-Key to deduplicate.

• Signature: Validate X-Summit-Signature (HMAC-SHA256) and timestamp window.

• Acknowledge: Respond 2xx within 10 seconds. Otherwise a retry is scheduled.

Webhook envelope:

{
 "delivery_id": "dwk_01HFX...",
 "event": "policy.submitted",
 "occurred_at": "2025-10-30T17:35:12Z",
 "attempt": 1,
 "data": { /* event-specific payload */ }
}

Event: policy.submitted

{
 "policy": {"policy_number": "ABC123456", "policy_type": "CGL", "effective_date": "2025-01-01", "expiry_date": "2026-01-01"},
 "certificate_holder": {"name": "ABC Apartments", "reference_ids": {"property_id": "KEL-001","unit_id": "Unit-204","lease_id": "L-7788","tenant_id": "RES-9981"}},
 "documents": {"coi_pdf_id": "doc_01H..."}
}

Event: policy.verified

{
 "policy": {"policy_number": "ABC123456", "verified_at": "2025-10-30T17:35:00Z", "verifier": "carrier-api"},
 "checks": [{"name": "limits", "result": "pass"}, {"name": "endorsements", "result": "pass"}],
 "certificate_holder": {"reference_ids": {"property_id": "KEL-001","unit_id": "Unit-204"}}
}

Event: policy.lapsed

{
 "policy": {"policy_number": "ABC123456", "lapsed_at": "2026-01-02T00:00:00Z"},
 "reason": {"code": "expiry", "detail": "No renewal received by expiry"},
 "last_known_coverage": {"effective_date": "2025-01-01","expiry_date": "2026-01-01"},
 "certificate_holder": {"reference_ids": {"property_id": "KEL-001","tenant_id": "RES-9981"}}
}

Event: policy.reinstated

{
 "policy": {"policy_number": "ABC123456", "reinstated_at": "2026-01-05T15:12:00Z", "new_expiry_date": "2027-01-01"},
 "reason": {"code": "late_renewal", "detail": "Carrier accepted late renewal"},
 "certificate_holder": {"reference_ids": {"property_id": "KEL-001","tenant_id": "RES-9981"}}
}

Retry policy, backoff, and deduplication

• Outbound webhooks: Up to 8 attempts over ~24 hours (0m, 2m, 10m, 30m, 2h, 6h, 12h, 24h) with full‑jitter backoff. Stop on any 2xx. 4xx (except 408/429/499) are not retried.

• Inbound uploads: If Summit returns 5xx or network timeouts, clients SHOULD retry with the same Idempotency-Key. If a job is already processing, 409 Conflict is returned with the existing job_id.

• Deduplication: Use delivery_id for webhooks; for inbound, Idempotency-Key and a hash of the request body.

Versioning and environments

• Versioning: URI-based (e.g., /v1/...). Breaking changes increment the major version.

• Environments: sandbox and production. Secrets and webhook signing keys are distinct per environment.

Document handling

• Formats: PDF preferred for COIs; images accepted (PNG/JPG) will be converted to PDF.

• Virus scanning: All documents scanned on ingest; infected files are rejected.

• Storage: Data is stored in Canada. See the Privacy Policy for retention and access rights.

Error model

• Error response schema:

{
 "error": {
 "code": "invalid_request",
 "message": "expiry_date must be after effective_date",
 "field": "policy.expiry_date",
 "correlation_id": "corr_01H..."
 }
}

• Common codes: invalid_request, unauthorized, forbidden, not_found, conflict, rate_limited, server_error.

Operational best practices

• Always include platform reference IDs (property_id, lease_id, unit_id, tenant_id) to ensure correct routing in Yardi/Buildium/Entrata/RealPage.

• Provide Additional Insured and Waiver of Subrogation flags explicitly; do not rely on free‑text notes.

• Send renewals at least 15 days before expiry_date to prevent automatic lapse notifications to properties.

• Keep webhook endpoints highly available; queue and process asynchronously using the delivery_id to guarantee exactly‑once effects in your system.

Support and change management

• Access, credentials, and environment setup: contact Summit via Contact Us.

• Claims coordination (post‑incident): see Claim Services.

• Property management domain context and coverages: see Property Management Insurance.

• Deprecations: Summit provides 90 days’ notice for breaking changes on stable versions.