Acrematic

Deep Research API

Send up to 1,000 Acrematic property IDs and get back a scored assessment and an estimated value range for each one.

Overview

Each analysis combines parcel, valuation and sales records with terrain, road access, flood and census data and satellite and Street View imagery, then has an AI model score the property.

A job takes from a few seconds to several minutes, depending on how many properties it holds and how many are already analysed.

Testing

Build and test against staging, https://ai-staging.acrematic.com, with your staging key. It has the same endpoints, responses and limits as production, and its usage is not billed. Switch the base URL and key to production when you go live.

Authentication

Every request needs your API key in the Authorization header. Acrematic issues one key per customer per environment; contact your Acrematic representative to get one.

Authorization: Bearer YOUR_API_KEY

• Call the API from your server only. Never put the key in a browser, mobile app or public repository.
• Requests without a valid key get 401 Unauthorized.
• Your key identifies your account for usage and billing, and you can only see jobs started with it.
• If a key may have leaked, tell us and we will revoke it and issue a new one.

Start a research job

POST/properties/deep_research

Starts a job and returns its job_id immediately, with status 202 Accepted.

Request body

Example

curl -X POST https://ai.acrematic.com/properties/deep_research \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "property_ids": ["177624185", "24432507"],
    "callback_url": "https://example.com/hooks/acrematic"
  }'

Response (202)

{
  "success": true,
  "job_id": "8f14e45f-ceea-467a-9a3c-2c1b4b3c6d01",
  "status": "started",
  "total_items": 2,
  "message": "Deep research job started. Poll /properties/deep_research/jobs/8f14e45f-ceea-467a-9a3c-2c1b4b3c6d01 for status."
}

Keep the job_id: you need it to fetch results.

Get job status and results

GET/properties/deep_research/jobs/{job_id}

Returns the job's progress and every result finished so far. Results appear as each property completes, so you can read partial results while the job runs.

curl https://ai.acrematic.com/properties/deep_research/jobs/8f14e45f-ceea-467a-9a3c-2c1b4b3c6d01 \
  -H "Authorization: Bearer YOUR_API_KEY"

Job status

Response fields

Each property's analysis

Nine attributes, each with a score from 1 to 10 (10 is best), a short summary and a detail explanation: slope, access, infrastructure, location, flood, environmental, view, neighborhood, comparable_value.

Alongside them: overall_assessment (text), estimated_value_range (low, high, basis), comp_summary, buildability, utilities (electricity, water, sewer, road_access), images used in the analysis, and metadata.

{
  "success": true,
  "job_id": "8f14e45f-ceea-467a-9a3c-2c1b4b3c6d01",
  "status": "completed",
  "total_items": 2,
  "processed_items": 2,
  "failed_items": 0,
  "progress_pct": 100.0,
  "results": {
    "177624185": {
      "slope": {"score": 7, "short": "Gentle slope", "detail": "..."},
      "access": {"score": 8, "short": "Paved road access", "detail": "..."},
      "flood": {"score": 9, "short": "Minimal flood risk", "detail": "..."},
      "overall_assessment": "Good development potential...",
      "estimated_value_range": {"low": 85000, "high": 125000, "basis": "Based on 12 comparable sales"},
      "utilities": {"electricity": true, "water": false, "sewer": false, "road_access": true}
    }
  },
  "errors": null,
  "created_at": "2026-10-26T15:02:11Z",
  "started_at": "2026-10-26T15:02:11Z",
  "completed_at": "2026-10-26T15:03:40Z"
}

The example is shortened; real results include all nine attributes and every field listed above.

Polling: check every 10 to 30 seconds and stop once status is completed or failed. Or skip polling and use a callback.

Completion callbacks

If you pass a callback_url, we POST to it once when the job finishes, whether it completed or failed, so you don't need to poll.

{
  "job_id": "8f14e45f-ceea-467a-9a3c-2c1b4b3c6d01",
  "event_name": "job_finished",
  "status": "completed",
  "total_items": 2,
  "processed_items": 2,
  "failed_items": 0
}

The callback is a notification only. Fetch the results with the GET request above.

• The URL must use https:// and point to a public internet address.
• We wait up to 5 seconds for your response and do not retry. Return any 2xx quickly and do your processing afterwards.
• Redirects are not followed.
• If your endpoint is down, the job is unaffected and its results stay available through the GET request.

Errors, limits and usage

Errors return a JSON body with a machine-readable code:

{
  "success": false,
  "error": {"code": "RATE_LIMITED", "message": "Daily limit of 5000 properties reached ...", "details": {}}
}

A property that can't be analysed doesn't fail the job: it appears under errors with its reason, and the rest of the job continues.

Limits

• 1,000 property IDs per job.
• 5,000 properties per API key in any rolling 24 hours, unless agreed otherwise.

Usage

Usage is metered per property analysed successfully, per production API key. Properties listed under errors are not counted, and staging usage is not billed. Pricing is set out in your agreement with Acrematic.