Most appraisal platform demos look great until someone from engineering on the AMC side asks three questions: Show me your webhook retry behavior. Prove the audit log hasn't been edited. What happens when an appraiser is offline for six hours in a rural county?
That's where a lot of vendors fall apart. The sales deck says "full API integration" and "complete audit trail," but there's no way to actually validate any of it. This checklist is the opposite of a sales deck — it's the acceptance criteria and test cases you'd run in the real world, whether you're building the platform or evaluating one.
If you want the buyer-side framing rather than the engineering-side framing, the companion piece compares platforms on these same four capabilities at a feature level. This article goes a layer deeper: concrete contract snippets, test definitions, and pass/fail thresholds. For the offline conflict-resolution patterns that underpin section three, the offline-first mobile workflows and conflict resolution guide is worth having open in another tab.
How to use this brief
Each of the four capabilities below has the same shape: required behaviors, a contract or schema snippet, and acceptance criteria written as things you can actually test. Treat the acceptance criteria as literal gates. "The API supports webhooks" is not a gate. "A webhook that returns 500 is retried with exponential backoff and surfaces in a dead-letter queue within 15 minutes" is a gate.
Worth naming upfront: the capabilities that pass a scripted demo and fail in production are almost always the ones involving time and failure. Idempotency under retries. Audit integrity after a database migration. Sync after a long offline window. Build your test data around failure, not the happy path.
1. API maturity checklist
The appraisal integration surface is more varied than people expect. AMCs push assignments in, pull status and deliverables out, and increasingly want event streams rather than polling. A mature API covers all three directions without forcing partners to poll your status endpoint every 30 seconds.
Manage every appraisal with confidence and clarity.
Rateoly helps you coordinate inspections, generate reports, and communicate seamlessly with clients.
- Comprehensive appraisal tracking
- Automated client notifications
- Integrated scheduling & report management
No credit card required
Required endpoints (minimum viable surface)
-
POST /assignments— create an order, returns assignment ID and idempotency acknowledgment -
GET /assignments/{id}— full status, current milestone, assigned appraiser -
PATCH /assignments/{id}— update due dates, fees, special instructions -
GET /assignments/{id}/deliverables— list of report versions with hashes -
POST /webhooks— register a subscription with event filters -
GET /events?since={cursor}— replayable event feed for partners who prefer pull
That last endpoint matters more than it looks. Webhooks fail. If a partner's endpoint is down for an hour, they need a way to catch up without you manually replaying events. A cursor-based event feed is the recovery path.
Webhook semantics
Webhooks are where most appraisal platforms are quietly broken. Common failures in real integrations: no signature on the payload, no retry on failure, and no way for the receiver to tell a replay from a first delivery.
{ "eventid": "evt01HQ8...", "eventtype": "deliverable.completed", "occurredat": "2026-03-14T18:22:04Z", "idempotencykey": "evt01HQ8...", "deliveryattempt": 1, "data": { "assignmentid": "asg7741", "deliverableversion": 3, "sha256": "9f2b...c01a" }, "signature": "t=1710440524,v1=5257a8..." }
The signature field is non-negotiable. Sign with HMAC-SHA256 over the raw body plus a timestamp, and reject payloads where the timestamp is older than five minutes to block replay attacks.
Retry policy acceptance criteria:
-
Non-2xx responses retried with exponential backoff (e.g., 1m, 5m, 30m, 2h, 6h)
-
After final retry, event lands in a dead-letter queue visible to the partner
-
Each retry carries the same
eventidand an incrementeddeliveryattempt
Auth, versioning, and limits
OAuth2 client credentials for server-to-server; short-lived JWTs for session contexts. Avoid long-lived static API keys as the only option — if a key leaks, rotation shouldn't require a partner code deploy.
| Concern | Weak implementation | Acceptance criterion |
|---|---|---|
| Auth | Single static API key | OAuth2 + rotatable credentials, scoped tokens |
| Versioning | "We're backward compatible" verbally | Published version + 12‑mo deprecation window |
| Rate limits | Undocumented, 429s with no headers | Documented limits, Retry-After + remaining-quota headers |
| Idempotency | None on create | Idempotency-Key header honored for 24h+ |
| Sandbox | None | Full sandbox with seedable test fixtures |
Idempotency test
Send the same POST /assignments with an identical Idempotency-Key three times in rapid succession. Pass: one assignment created, two responses return the original resource. Fail: two or three assignments created. This single test catches more real-world billing and duplication bugs than almost anything else in this document.
2. Audit‑trail design and validation
An audit trail that can be edited is not an audit trail. For appraisal work, where files surface in litigation and regulatory reviews years later, "append-only" has to be provable — not just asserted in a readme.
Immutable event model
Every meaningful action writes an event to an append-only store. No updates, no deletes — corrections are new events that reference the prior one. Required fields on each event:
-
event_id(globally unique) -
actor(user ID, service account, or system) -
occurred_at(timestamp with timezone offset, not naive local time) -
source(which subsystem emitted it) -
payload(the change itself) -
prev_hash(hash of the previous event in the chain) -
hash(hash of this event's canonical form includingprev_hash)
{ "eventid": "aud0192...", "actor": "user441", "occurredat": "2026-03-14T13:22:04-05:00", "source": "report-service", "action": "narrative.edited", "payload": { "section": "reconciliation", "fieldlendelta": 212 }, "prev_hash": "8c1f...aa90", "hash": "e77b...12dc" }
Tamper evidence that holds up
Hash chaining catches edits internally. For external defensibility, periodically anchor the chain: compute a Merkle root over a batch of events (say, daily) and sign it with a key held outside the application database. Some teams anchor the daily root to a notarization service or a timestamping authority. The point is that an attacker who compromises the application DB still can't forge a valid signed root.
One timezone issue that consistently bites people: storing occurred_at without an offset makes forensic reconstruction unreliable across daylight-saving boundaries. A review signed at "1:30 AM" during the fall-back hour is genuinely ambiguous without the offset. Always store offset-aware timestamps.
Retention and export
Export formats should match who's asking. Attorneys want PDF with a cover page and verification instructions. Engineers and analysts want JSONL so they can replay. Spreadsheet-driven reviewers want CSV. Support all three, and include the signed Merkle root in the export so the recipient can verify independently.
Forensic reconstruction test cases
-
Chain integrity Pull the full event chain for one assignment, recompute each hash from
prev_hash, confirm the final hash matches the signed root. Pass = zero mismatches. -
Tamper detection In a test environment, manually edit one historical payload in the store, re-run verification. Pass = verification fails and points to the first broken event.
-
Reconstruction From the event chain alone, rebuild the state of a report at a specific past timestamp. Pass = reconstructed state matches a snapshot taken at that time.
If test two doesn't fail loudly, your tamper evidence is decorative.
3. Offline mobile sync checklist
Field inspection is the hard part. Appraisers work in basements, rural dead zones, and new construction with no signal. The data model has to assume offline is the normal state, not the exception. The design patterns for merge strategies are covered in depth in the offline-first mobile workflows guide — this section is the validation layer on top of those patterns.
Data partitioning and partial sync
Don't sync the whole database to a phone. Partition by assignment and sync only what the appraiser has active, plus reference data (comps, forms) that's reasonably small. A full-sync-only design falls over the moment an appraiser has 40 active files and a slow connection.
Sync metadata every record needs
-
record_idandversion(monotonic per record) -
updated_at(device clock, offset-aware) -
server_seq(assigned on successful sync) -
deletedtombstone flag (never hard-delete offline-mutable records) -
device_id(which device made the change)
Tombstones matter because without them, a record deleted on one device reappears after sync from another device that never saw the delete.
Conflict detection and merge strategy
Detection: compare version and server_seq. If both sides changed a record since the last common version, that's a conflict. Merge strategy depends on the field:
-
Last-write-wins — fine for simple scalar fields like a checkbox or a single measurement
-
Per-field merge — appraiser A edits condition notes, appraiser B edits square footage; merge both rather than overwrite
-
CRDT structures — for genuinely concurrent collaborative fields like a running notes list, where neither side should lose data
The mistake that shows up most often: last-write-wins applied blindly to an entire record. Two appraisers — or one appraiser on phone and tablet — touch the same file, and the second sync silently overwrites the first one's photo captions. The data loss is invisible until a lender exception surfaces weeks later.
Protocol: delta sync with checkpointing
Use delta sync keyed on server_seq. The client sends "last seq I have is 4412," the server sends everything after. Checkpoint frequently so an interrupted sync resumes rather than restarts — critical on bad connections where a 30-second window is all you get.
A simple diagram of delta sync with checkpointing and conflict resolution.
Checkpoint frequently so an interrupted sync resumes rather than restarts — critical on bad connections where a 30-second window is all you get.
Offline UX acceptance
-
App is fully usable offline, including creating new assignments and attaching photos
-
Pending-sync state is visible per record, not just a global spinner
-
Conflicts surface to the appraiser with both versions shown, not auto-resolved silently when the merge is ambiguous
The long-offline test
This is the one most platforms skip. Put a device offline, make 50+ edits across 10 assignments over a simulated six-hour window, modify some of the same records from a second device and the server, then reconnect.
-
No data loss on any record
-
All true conflicts detected and surfaced
-
Tombstones honored (deleted records stay deleted)
-
Sync completes within a reasonable window and resumes if interrupted mid-stream
Run this with an artificially throttled connection and with a forced disconnect halfway through sync. If it only works on hotel wifi, it doesn't work.
4. Billing automation hooks
Billing bugs in appraisal platforms share one root cause: events that fire more than once, or not at all. Both corrupt the invoice.
Metering event types
-
assignment.accepted -
deliverable.created -
review.completed -
revision.requested -
rush.flagged
Each metering event carries an idempotency_key. When the same deliverable.created event is delivered twice — and it will be, because retries exist — the billing engine must charge once.
{ "meterevent": "deliverable.created", "idempotencykey": "asg7741:deliverable:v3", "assignmentid": "asg7741", "billableunits": 1, "occurred_at": "2026-03-14T18:22:04Z" }
Note the idempotency key is derived from the business fact (asg_7741:deliverable:v3), not a random UUID. This way, even if the upstream system generates two separate event objects for the same deliverable, they collapse to one charge.
Webhook reconciliation
The billing provider's webhooks (charge succeeded, payment failed) need the same retry and dead-letter handling as section one. On top of that, run a daily reconciliation job: compare internal metered events against the billing provider's recorded charges, flag any delta.
Billing test cases
-
Duplicate meter event Fire
deliverable.createdtwice with the same key. Pass = one charge. -
Out-of-order delivery Deliver
review.completedbeforedeliverable.created. Pass = engine handles gracefully, no phantom charge. -
Reconciliation delta Inject a metered event that never reached billing. Pass = daily recon flags it within the tolerance window.
-
Dispute handling Mark a charge disputed. Pass = future metering continues, disputed charge isolated, audit event written.
Each metering event carries an idempotency_key. When the same deliverable.created event is delivered twice — and it will be, because retries exist — the billing engine must charge once.
KPIs and acceptance criteria
These are the numbers worth putting in a contract or an internal SLO. They're ranges, not promises — tune to your scale.
| Capability | Metric | Target |
|---|---|---|
| API | p95 response latency | under ~300ms for reads |
| API | Webhook delivery success (incl. retries) | 99.9%+ |
| Audit | Tamper-detection rate | 100% (zero tolerance) |
| Audit | Chain verification failures in prod | 0 |
| Sync | Divergence rate (unresolved conflicts) | well under 1% of synced records |
| Sync | Long-offline data loss | 0 |
| Billing | Reconciliation delta | under ~0.1% of charges, auto-flagged |
Set operational alerts on the ones where the acceptable value is zero: any audit chain verification failure, any long-offline data-loss event, any reconciliation delta above tolerance. Those should page someone, not sit in a dashboard.
Red flags and rollout checklist
A few implementation patterns that look fine in a demo and break in production:
-
"We have webhooks" but no signatures or retries. The demo fires one webhook to a listening endpoint. Production has outages. Ask to see the dead-letter queue.
-
Audit log in the same mutable table as app data. If a support engineer can
UPDATEan audit row, it's not an audit trail. Ask whether it's append-only at the storage layer. -
Offline sync that only does last-write-wins on whole records. Ask specifically about per-field merges and run the long-offline test.
-
Billing keyed on random UUIDs instead of business facts. Guarantees duplicate charges under retries.
-
Naive timestamps. No timezone offset anywhere is a forensic liability.
A rollout sequence that tends to work:
-
Stand up the sandbox and seed realistic test fixtures first.
-
Run the idempotency and duplicate-charge tests before anything else — they catch the costliest bugs.
-
Run the long-offline sync test with throttling and forced disconnect.
-
Run the tamper-detection test and confirm it fails loudly.
-
Only then wire up a real partner in a limited pilot.
When this depth is overkill
A two-person shop doing 30 orders a month through a single AMC portal doesn't need Merkle-anchored audit trails and CRDT merges. The right scope there is signed webhooks, append-only logging, and solid idempotency. The full checklist earns its keep when you're integrating with multiple AMCs, carrying files into litigation territory, or putting dozens of appraisers in the field on offline devices.
The common thread across all four capabilities: the happy path always passes. Build your acceptance tests around retries, long offline windows, tampered records, and duplicate events. That's where real platforms separate from good-looking demos — and it's exactly the ground AMC engineering teams will walk you across during due diligence.
Ready to elevate your appraisal operations?
Join 500+ appraisal firms using Rateoly to enhance accuracy, save time, and improve client satisfaction.