R

ROYKANDEVELOPERS

ROYKAN PROOF API / PILOT CONTRACT

From property-photo request to reviewable result.

Create one asset-specific capture session, send the returned hosted link, and retrieve a stable evidence decision. Production access is issued to approved design partners.

Run sandbox →Request production access
01 / QUICKSTART

Create a capture session

Use a server-side API key. The response includes a short-lived hosted capture URL and a stable session ID. Send the URL through your existing resident communication workflow.

curl https://roykan.com/api/v1/proof/capture-sessions \
  -H "Authorization: Bearer $ROYKAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "check_2026_1042",
    "property_reference": "prop_83K2",
    "unit_reference": "unit_14B",
    "asset_type": "under_sink_plumbing",
    "expires_in_hours": 72
  }'
Keep API keys server-side.

Never place a production key in a browser, resident link, mobile bundle, or public repository.

02 / AUTHENTICATION

Bearer API keys

Production endpoints require Authorization: Bearer rk_live_…. Roykan stores configured key hashes rather than requiring resident credentials. Sandbox calls do not need a key.

03 / ASSET TYPES

Water-loss evidence pack v1

asset_typeRequested view
under_sink_plumbingSupply lines, valves, drain, cabinet base
toilet_supply_and_baseShutoff, supply line, tank connection, base
washer_connectionsHot/cold connections, hoses, drain, floor
water_heater_baseLower unit, pan, visible valves, floor
hvac_condensate_areaVisible line, drain or pan, surrounding floor
04 / ENDPOINTS

Pilot surface

POST/api/v1/proof/capture-sessions

Create a hosted photo request.

GET/api/v1/proof/capture-sessions/:id

Retrieve session state and latest review.

POST/api/v1/proof/capture-sessions/:id

Upload a photo server-to-server using multipart field photo.

DELETE/api/v1/proof/capture-sessions/:id

Delete the session, review records, and stored evidence.

POST/api/v1/proof/sandbox

Return a synthetic decision with no key or photo.

05 / DECISION CONTRACT

Four bounded outcomes

visible_issue_detected

A concrete visible condition is present. Route to manager review.

no_visible_issue_detected

Usable view; no listed issue is apparent. This is not a safety declaration.

insufficient_evidence

Ask for another photo because the evidence is not reviewable.

human_review_required

Evidence is ambiguous or automated review is unavailable.

{
  "status": "complete",
  "latest_verification": {
    "decision": "visible_issue_detected",
    "capture_quality": "usable",
    "asset_match": true,
    "confidence": 0.91,
    "findings": [{
      "category": "water",
      "severity": "prompt_review",
      "observation": "Dark discoloration is visible below the drain connection."
    }],
    "suggested_next_step": "Have a property manager review the evidence."
  }
}
06 / ERRORS

Predictable JSON errors

Non-2xx responses use {"error":{"code":"…","message":"…"}}. Common codes include authentication_required, invalid_api_key, invalid_asset_type, session_expired, attempt_limit_reached, and service_not_configured.

07 / PRIVACY BOUNDARY

Use opaque references

Send internal property and unit IDs—not resident names, emails, lease text, or full addresses. Hosted capture asks for one focused asset photo and a submission confirmation. Your production agreement sets retention and review responsibilities.

Human authority is required.

Do not use a Roykan result by itself to charge a resident, assign fault, issue a legal notice, bypass emergency procedures, or replace professional inspection.

08 / INTERACTIVE SANDBOX

Inspect the response contract

Choose an asset and a synthetic scenario. The sandbox helps your team map statuses before production credentials or resident evidence are involved.

Synthetic data only. This sandbox does not upload or analyze a photo.

Select a scenario and run the synthetic response.