Distress Meter AI
Distress Meter AI
Auth loading...
Home Pricing Blog Affiliates B2B Partners API
API Help · Swagger · Login to get API Key

Analyze addresses via JSON or CSV and get a 0–10 distress score with a short exterior summary.

API Key auth · Batch-friendly · 1 address = 1 billing unit

Base URL: https://api.distressmeter.ai/v1 (same as the web app uses).

Replace BASE_URL and API_KEY (your dm_live_... key from the API Key page).

Copy/paste examples:
Minimal steps to integrate:
  1. Choose an API plan on Pricing.
  2. Generate your API key on the API Key page (after login). Use it in every request as Authorization: Bearer dm_live_...
  3. Create a job (JSON, JSON upload, or CSV), poll status, then download results as output.csv or output.json.
Use Swagger to try the API
1) Create job (JSON batch)
Endpoint: POST /v1/distress
Submit a plain list of address strings. Output is CSV.
curl -X POST "BASE_URL/v1/distress" \ -H "Authorization: Bearer API_KEY" \ -H "Content-Type: application/json" \ -d ‘{ "source": "api", "addresses": [ "123 Maple St, Springfield, IL 62704", "456 Oak Ave, Springfield, IL 62704" ] }’
Response: { "jobId": "..." } — use jobId to poll status and download output.csv.
2) Create job (CSV upload)
Endpoint: POST /v1/distress/csv (multipart/form-data)
Upload a CSV file with an address column. Output is CSV.
curl -X POST "BASE_URL/v1/distress/csv" \ -H "Authorization: Bearer API_KEY" \ -F "[email protected]" \ -F "source=csv" \ -F "strict=false"
Response: { "jobId": "..." } — use jobId to poll status and download output.csv.
3) Create job (JSON upload)
Endpoint: POST /v1/distress/json
Submit addresses with an optional per-row id (e.g. a property ID from your system) — it is echoed back as data[].id in the output so you can correlate results with your own records. Output is JSON.
curl -X POST "BASE_URL/v1/distress/json" \ -H "Authorization: Bearer API_KEY" \ -H "Content-Type: application/json" \ -d ‘{ "source": "api", "addresses": [ { "id": "prop_001", "address": "123 Maple St, Springfield, IL 62704" }, { "id": "prop_002", "address": "456 Oak Ave, Springfield, IL 62704" } ] }’
Response: { "jobId": "..." } — use jobId to poll status and download output.json.
4) Poll status
Endpoint: GET /v1/distress/{jobId}
Check processing progress. When status is "completed" the job is ready to download.
curl -X GET "BASE_URL/v1/distress/JOB_ID" \ -H "Authorization: Bearer API_KEY"
Response: { "jobId", "status", "total", "done", "percentageDone", "outputDownloadUrl", "error" }
5) Webhook push (optional)
Instead of polling, configure a webhook URL on your account and the API will POST job status automatically on every status change (queued → processing → finalizing → completed or error).
Set your webhook URL on the Settings page (coming soon), or contact support.
Payload sent to your URL (same shape as GET /v1/distress/{jobId}):
POST https://your-server.example.com/webhook Content-Type: application/json { "jobId": "11668fafc4d847d5bd7e9444698e5b08", "source": "api", "status": "completed", "total": 250, "done": 250, "percentageDone": 100, "outputDownloadUrl": "BASE_URL/v1/distress/JOB_ID/download", "error": "", "hasErrors": false, "createdUtc": "2025-01-15T10:00:00Z", "processingStartedUtc": "2025-01-15T10:00:05Z", "completedUtc": "2025-01-15T10:04:22Z" }
Delivery: 3 attempts with 1.5 s intervals. Your endpoint should return 2xx. Use the test endpoint below to verify your receiver works before going live.
curl -X POST "BASE_URL/v1/account/webhook/test" \ -H "Authorization: Bearer API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "test", "jobId": "ping" }'
Test endpoint logs the received payload server-side and returns { "received": true }. Use it as your webhook URL during development.
6) Download output
Endpoint: GET /v1/distress/{jobId}/download?mode=stream
Returns output.csv or output.json depending on the job type. Use ?mode=stream when downloading via fetch — browsers can’t attach an Authorization header to a plain link click.
curl -L "BASE_URL/v1/distress/JOB_ID/download?mode=stream" \ -H "Authorization: Bearer API_KEY" \ -o output.csv
Response: file stream with Content-Disposition: attachment; filename="output.csv" (or output.json for JSON jobs).
Authentication
Use your API key in every request header.
Authorization: Bearer dm_live_xxxxxxxxxxxx...
  • API key (dm_live_...) — for programmatic access from your code. Long-lived (1 year). Generate it on the API Key page.
  • Key is user-scoped — all billing is tied to your account.
  • Keep it secret. Revoke and regenerate if exposed.
Note: The API Key page also offers a short-lived JWT token for manual testing in Swagger or browser tools. Do not use the JWT in production code — it expires in ~1 hour and cannot be refreshed programmatically. Always use the API key (dm_live_...) in your integrations.
Usage & limits
Check remaining addresses for the current billing period.
Endpoint: GET /v1/billing/usage
curl -X GET "BASE_URL/v1/billing/usage" \ -H "Authorization: Bearer API_KEY"
Response includes: baseLimit, addonLimit, effectiveLimit, reserved, consumed, available, periodStartUtc, periodEndUtc
Endpoints
Core API endpoints used by the portal.
  • POST /v1/distress — create job from JSON (source, addresses); output is CSV
  • POST /v1/distress/json — create job from JSON with per-row id (source, addresses: [{address, id?}]); output is JSON
  • POST /v1/distress/csv — create job from CSV (multipart: file, source, strict); output is CSV
  • GET /v1/distress — job history (query: limit)
  • GET /v1/distress/{jobId} — job status
  • GET /v1/distress/{jobId}/download — output.csv (?mode=stream supported)
  • GET /v1/distress/{jobId}/{sha}.jpg — public Street View image URL (no auth)
  • GET /v1/billing/usage — usage snapshot
  • POST /v1/account/webhook/test — log a test webhook payload server-side (returns {"received":true})
Response examples
Shapes reflect what the portal expects from the API.
Job status JSON
{ "jobId": "11668fafc4d847d5bd7e9444698e5b08", "status": "running", "total": 250, "done": 42, "percentageDone": 16.8, "outputDownloadUrl": "BASE_URL/v1/distress/11668fafc4d847d5bd7e9444698e5b08/download", "error": null }
output.csv row
address,distress,notes,imageUrl "123 Maple St, Springfield, IL 62704",7,"damaged siding; peeling paint; overgrown yard","BASE_URL/v1/distress/JOB_ID/SHA.jpg"
Common errors
  • 401 — missing, invalid, or expired API key
  • 400 — invalid request (missing addresses / wrong form-data)
  • 404 — job not found (or not accessible)
Notes
  • Only successfully processed addresses are billed.
  • Street View image URLs in output.csv are public short links.
  • AI-generated estimates for informational purposes only.