Integrations
Draft · protocol 3.0.0-draft
Design objective: no additional portal
Section titled “Design objective: no additional portal”The contractor is frequently the only source of ground-truth job data, and duplicate entry reduces participation. TRP supports embedded data capture through contractor tools, restoration platforms, estimating software, insurer claims systems, mobile capture and existing document flows. A vendor-specific user interface is an option, never a precondition for adoption.
Integration modes
Section titled “Integration modes”| Mode | Data flow | Appropriate use |
|---|---|---|
| Server-to-server API | Partner sends jobs and events; receives results | High-volume enterprise partners |
| Embedded component | Partner authenticates and shows focused tasks | An existing portal with missing capture fields |
| File and document ingestion | Estimate PDFs, CSV, receipts, manifests | Legacy or low-code integrations |
| Event webhook | Job changed, ticket created, quote updated | Near-real-time synchronization |
| Mobile QR and ticket capture | Waste load and evidence at point of activity | Field workflows |
| Batch exchange | Scheduled claim portfolios | Initial carrier pilots |
Adapter capabilities
Section titled “Adapter capabilities”An adapter built against a partner’s actual, permitted API and data rights may:
- read claim and job identity, region and damage category;
- read estimates, revisions and line items where permitted;
- capture waste events, receipts, photos and material choices from the existing workflow;
- return an impact summary and a list of eligible alternatives;
- write back recommendation status, approved selection and evidence links where supported;
- synchronize corrections and preserve provenance of every incoming field.
Do not assume a partner supports a particular write-back event until it is validated with that partner.
Mapping register
Section titled “Mapping register”Each connector needs a signed-off mapping sheet: partner field, TRP field, transformation, unit conversion, enum mapping, required or optional, sensitivity, source of truth, sync direction, deletion handling and a test fixture. Keep explicit mappings for duplicate claims across insurer and contractor systems. Use stable idempotency keys for event ingestion.
Transport independence
Section titled “Transport independence”TRP defines payload semantics, not a transport. Implementations may use REST, GraphQL, webhooks, files or event streams.
Proposed webhook event types
Section titled “Proposed webhook event types”trp.claim.created, trp.estimate.revised, trp.mitigation.recorded, trp.waste.recorded, trp.waste.verified, trp.product.mapped, trp.option.assessed, trp.decision.approved, trp.material.installed, trp.impact.recalculated, trp.report.published, trp.evidence.invalidated.
Each event includes an event ID, tenant, resource, revision, occurred and received times, a signature and retry metadata. Delivery MUST be safe under at-least-once semantics through idempotency keys.
Security and privacy expectations
Section titled “Security and privacy expectations”- Use OAuth 2.0 or OIDC, or securely managed service-to-service credentials, with least-privilege scopes.
- Encrypt data in transit and at rest and enforce tenant isolation.
- Sign webhooks; enforce request-size limits, upload scanning, file-type restrictions and rate limits.
- Keep audit logs and defined retention schedules.
- Never put credentials or tokens in documentation examples.
- Public examples are synthetic. Claims contain names, addresses, policy numbers, photographs and commercial pricing, and must be separated from publishable aggregates.
- Distinguish raw customer data, licensed supplier data, generated analyses and aggregated, de-identified metrics when stating who owns what.