TrueViewly Portal

Integration guide

How the API works

The API creates production-ready location-risk reports from latitude/longitude coordinates. Reports are generated asynchronously and can be consumed as JSON summaries, full report JSON, branded PDFs, batch result files, or webhook events.

Quickstart

Create an API key in the authenticated Developer area.
Create a report job with coordinates.
Poll the job URL until it is completed.
Fetch `detail=summary` for integration-friendly output.
Register a webhook or create a batch when your workflow scales.

curl -X POST "$BASE_URL/api/v1/location-risk/report-jobs" \
  -H "Authorization: Bearer $TRUEVIEWLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-001-2026-06-01" \
  -d '{"latitude":36.98154,"longitude":-122.02934}'

Authentication

Send the API key as a bearer token. `X-API-Key` is also accepted for systems that cannot set the Authorization header.

Authorization: Bearer tvly_live_...

Store API keys like passwords. Use scoped keys, expiration dates, and IP allowlists for production integrations.

Async Jobs

Report generation is asynchronous. Create a job with `reports:create`, then poll with `reports:read`. Completed jobs include report and PDF links.

{
  "jobId": "job_xxxxx",
  "status": "completed",
  "result": {
    "reportId": "00000000-0000-0000-0000-000000000000",
    "reportUrl": "/api/v1/location-risk/reports/00000000-0000-0000-0000-000000000000",
    "pdfUrl": "/api/v1/location-risk/reports/00000000-0000-0000-0000-000000000000/pdf"
  }
}

Reports

Use `detail=summary` for clean decision fields: overall score, risk level, confidence, top risks, module scores, recommendations, review flags, and links. Use `detail=full` for the complete module payload.

GET /api/v1/location-risk/reports/{reportId}?detail=summary
GET /api/v1/location-risk/reports/{reportId}?detail=full
GET /api/v1/location-risk/reports/{reportId}/pdf

Batch API

Batch API accepts up to 100 coordinate items. Each valid item becomes a normal async report job, so quotas, retries, reports, and webhooks stay consistent.

{
  "name": "West Coast sample",
  "items": [
    { "externalId": "site-001", "latitude": 36.98154, "longitude": -122.02934 },
    { "externalId": "site-002", "latitude": 33.248205, "longitude": -116.670794 }
  ]
}

Webhooks

Webhooks let TrueViewly call your system when a job completes or fails. Verify every event with the signing secret returned when the endpoint is created.

TrueViewly-Timestamp: 1780300800
TrueViewly-Signature: v1=...
TrueViewly-Event: report.job.completed
TrueViewly-Delivery: wd_xxxxx

Compute HMAC-SHA256 over `{timestamp}.{rawRequestBody}` using the `whsec_...` signing secret. Reject timestamps older than five minutes to reduce replay risk.

Usage and Quotas

Usage endpoints expose current quota, remaining calls, reset windows, and daily usage history. Existing `reports:read` keys can read usage, while new keys should use `usage:read`.

GET /api/v1/usage/current
GET /api/v1/usage/history?bucket=api&days=30

Error Catalog

Code	Status	Meaning	Fix
`invalid_api_key`	401	API key is missing, invalid, expired, revoked, or blocked by IP allowlist.	Check the key and allowed IPs.
`insufficient_scope`	403	The API key does not include the required scope.	Edit scopes or create a scoped key.
`quota_exceeded`	429	The billing-period API quota is exhausted.	Wait for reset or upgrade plan.
`invalid_latitude`	400	Latitude is missing or outside -90..90.	Send a valid coordinate.
`invalid_longitude`	400	Longitude is missing or outside -180..180.	Send a valid coordinate.
`unsupported_location`	422	Coordinate is outside supported United States coverage.	Use US coordinates.
`idempotency_conflict`	409	The same key was used with a different payload.	Use a new idempotency key.
`report_job_not_found`	404	Job does not belong to the authenticated owner.	Check job id and API key.
`batch_not_found`	404	Batch does not belong to the authenticated owner.	Check batch id and API key.
`rate_limit_exceeded`	429	Too many requests in the rate-limit window.	Back off and retry later.

Versioning

Current endpoints are under `/api/v1`. Additive fields can appear without a version change. Breaking changes will use a new URL version and a deprecation period for v1.

TrueViewly API v1