From address to reviewed measurement.

Your first measurement#

1. Create your account.

   Open Create account and enter your email, password and company name. Passwords must be 8–128 characters. Confirm your email, then complete your company profile.

2. Check your searches.

   Every new measurement is one search. Free comes with a monthly allowance of searches and needs no card. Pro and Pro Plus start with welcome searches, then pay for each search from your balance. Your workspace shows what you have left, and Plans & billing explains the rest.

3. Enter the property address.

   Choose New measurement and use a full street address, including the street number, city, state and postal code. Check that the returned property is the one you intended.

4. Let the measurement finish.

   The job runs in the background and is saved to your account. Closing the tab does not cancel a submitted measurement. Return to saved history to check its state instead of starting a duplicate.

5. Inspect the result.

   Compare the turf outlines with the overhead image. Read source dates, review notes and any partial-result warnings before using the area in a customer estimate.

How a measurement works#

A submission creates a saved job first. Imagery acquisition and measurement happen afterward, so a successful submission is not a finished result.

The processing status and the result quality answer different questions. completed means processing finished; it does not certify the property boundary or every patch of turf. Check the result status and evidence too. A usable partial result counts as a charged search.

Reading saved history, refreshing a result or replaying the same integration request does not start another measurement. A new request is a new attempt. Reusing a request ID with changed input returns a conflict.

Review & saved history#

Open Measurements to find an address, compare completed and failed attempts, and filter by your review rating. Open a row to return to its original result.

Read the image and the numbers together

• Check the target property, visible turf outlines and any gaps caused by trees, shadows or incomplete imagery.
• Review the area, processing status, result quality and run time. Unavailable is not zero. Unknown areas and costs remain empty or null.
• Inspect supporting imagery and its source date separately. A saved reference may be labeled as not used in the measurement.
• Use Open Google Maps for location context. A property location pin does not establish a legal parcel boundary.

Keep a review record

Choose Not reviewed, Terrible, Needs work or Acceptable, add review notes, and select Save feedback. These are your own review labels. Feedback stays with the saved measurement and does not rewrite the original image, outlines or provider evidence.

Use the saved-property map

The map shows loaded measurements that have saved coordinates. Open a point to inspect its measurement. Entries without recorded coordinates still appear in the list; the map is not a completeness check for your entire history.

Export diagnostics for a review

Select the relevant history rows and use the diagnostic export action to download clarity-measure-diagnostics.json. An administrator also sees a Result diagnostics section on each saved result. These records help explain timing, status and evidence; they are not a survey or a finished customer quote. For geometry and image data in your own application, use the result API.

Imagery & quality#

Measurements use calibrated overhead imagery. Street View, when available, provides supporting context. It is not the image plane used to calculate turf area.

Use on-site verification when the result cannot support your decision. Current integrations accept turf plus driveway, sidewalk and paving (parking and patios) in the same fast pass; a public sidewalk is measured and published on its own and is never counted as the customer’s ground. Trees and shrubs are not measured yet. Any roof-edge geometry encountered in research or older records describes horizontal plan lengths, not pitch-corrected installation lengths. Candidate crown counts are not complete tree or plant inventories.

Plans & billing#

Clarity Measure is sold by the search. A search is one measurement of one address, whether it starts in the workspace, from a contact-form lead, or through the API or MCP, and it costs the same whatever the mode. Current prices and allowances are on the pricing page.

How a search is charged

Starting a measurement reserves one search: a free search on Free, a welcome search while you have any, and otherwise your plan’s search price from the balance. A usable completed result settles the reservation. A failed attempt that produces no usable measurement gives it all back: the free search, the welcome search or the money. The reservation can remain while completion is still being reconciled; refreshing saved results or the dashboard checks the saved state.

A failed attempt is not charged, and it never locks the address: you can measure the same address again whenever you like. Sending repeated new request IDs for one request is still not a remedy for a conflict.

Your balance and auto top-up

On Pro and Pro Plus, add funds in Settings through Stripe checkout. Funds are non-refundable and never expire, and there is no monthly reset. Auto top-up is optional: it charges your saved card the amount you choose whenever the balance drops below the level you choose, and it turns itself off and emails you if a charge is declined. If you cancel a paid plan, the balance stays on your account and works again when you resubscribe. Free cannot add or spend funds.

When a search cannot start

• Free searches used. Wait for your next month, which starts on your signup day, or move to Pro or Pro Plus. New leads still arrive but are not measured automatically.
• Balance too low. Add funds, or turn on auto top-up.
• Pro Plus without a key. Once the welcome searches are used, add your OpenAI key in Settings. The step-by-step guide shows every click, from making the key to seeing it marked Valid.
• Thorough. Pro and Pro Plus measure with Standard, and with the one-pass quick mode through the API. Thorough stays on earlier credit plans.

Earlier credit plans

Accounts still on an earlier credit plan keep credits. The one-pass quick mode costs one credit, Standard reserves two credits and returns one when no review ran, Fast (Standard on priority processing) costs twice Standard's credits, and Thorough costs three credits. A failed attempt returns its credits, and purchased credits stay on the account after cancellation.

Recorded service costs are different from what you pay

Unknown costs remain unknown. Model and imagery figures do not include all hosting or operating costs, and are not a new charge to your payment method.

Account & email#

Sign in with your email and password at app.claritymeasure.com. Your email must be confirmed before you can use the workspace. Edit your company name, profile and measurement email preference in Account.

Confirm an account or reset a password

Open verification and password-reset links in the same browser where you requested them. The link uses a browser-bound verification step. If you see a browser or expired-link error, return to sign-in and request the relevant flow again. For a forgotten password, use Forgot password?, follow the email link and choose a new password.

Measurement notifications

When enabled and a verified recipient is available, the service sends a welcome message and notifications for completed or failed measurements. A notification links to the signed-in saved result; it does not make the measurement public. Email delivery can lag behind the saved job, so the workspace is the place to check its state.

Transactional messages use noreply@claritymeasure.com with replies directed to support@claritymeasure.com. Check spam folders if a message is missing. Support replies remain available in your workspace even when an email has not arrived.

API quickstart#

The canonical API origin is https://app.claritymeasure.com. Run these examples from a trusted server or terminal. They assume you have stored your key as CM_API_KEY in a protected environment.

The API and MCP are on Pro and Pro Plus. A Free account cannot create keys, and any call from a Free account is refused with 403 and plan_required.

Create a scoped key

Open API keys in your workspace. Name a key for its integration and select Create API key. The current workspace creates keys with both read and write scopes. The complete key is shown only once. Keep it in a secret manager, never in a web page, mobile bundle, source repository or support message.

The backend also supports keys with a single scope, although the current key-creation form does not offer a scope selector. A full submit-and-poll integration needs both scopes. Revoke a lost or exposed key in the workspace, then create and configure a replacement.

1. Confirm access without starting work

curl --fail-with-body 'https://app.claritymeasure.com/api/v1/measurements?limit=5' \
  -H "Authorization: Bearer $CM_API_KEY"

2. Read the current measurement options

This read-scope endpoint takes no parameters and starts no work. It reports the modes with what each costs on your plan and the current default, which part of the property is measured, the strip-to-the-curb switch, and the services measured today.

curl --fail-with-body 'https://app.claritymeasure.com/api/v1/measurement-options' \
  -H "Authorization: Bearer $CM_API_KEY"

3. Start a turf measurement

Generate a UUID, save it as CM_IDEMPOTENCY_KEY, and save the exact request body before sending. Replace the illustrative address below with the intended property. This action starts a search. On Pro and Pro Plus it is charged at your plan’s search price whatever the mode. On an earlier credit plan it costs one credit for Fast, and two reserved for Auto with one returned when it made one pass.

curl --fail-with-body 'https://app.claritymeasure.com/api/v1/measurements' \
  -H "Authorization: Bearer $CM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $CM_IDEMPOTENCY_KEY" \
  --data '{"address":"123 Example Street, Aurora, CO 80015","requested_services":["turf"],"requested_zones":"both","curb_strip":true,"measurement_mode":"quick"}'

A successful submission returns HTTP 202 and a Location header with the polling path. These UUIDs are illustrative:

{
  "measurement_id": "ef2892f0-3b0e-4b78-a78e-28e1e1eb8ecb",
  "status": "queued",
  "idempotency_key": "78f41919-3a9d-470e-9627-a43fb52328ed",
  "poll_url": "/api/v1/measurements/ef2892f0-3b0e-4b78-a78e-28e1e1eb8ecb",
  "result_url": "https://app.claritymeasure.com/app#measurement/ef2892f0-3b0e-4b78-a78e-28e1e1eb8ecb"
}

4. Poll the saved job

Set CM_MEASUREMENT_ID to the returned measurement ID. It may be different from your idempotency UUID.

curl --fail-with-body "https://app.claritymeasure.com/api/v1/measurements/$CM_MEASUREMENT_ID" \
  -H "Authorization: Bearer $CM_API_KEY"

Poll about once every five seconds while pending, with backoff for errors. Stop when measurement.status is completed or failed. Then inspect measurement.result_status, the saved result and its review notes. The result_url requires the account holder to sign in.

API reference#

All endpoints require Authorization: Bearer <key>. Requests and responses use JSON. The service rejects unexpected fields and duplicate parameters. The API is intended for server integrations; browser origins are restricted.

POST /api/v1/measurements

Requires write scope and one Idempotency-Key header containing a hyphenated UUID.

Returns the submission shape above with HTTP 202. Reuse the same UUID and identical body after a timeout or uncertain response, including retries through MCP. The same request returns the existing job and does not reserve a second search. Changed input with the same UUID returns 409.

Driveways, sidewalks and paving

Choose any mix of the lawn and the hard surfaces in requested_services, measured in one pass at the same price per search whatever you pick. The lawn is optional: a pressure-washing or snow company can send ["driveway"] or ["driveway","sidewalk"] alone. Omitted, it is ["turf"], the lawn only, exactly as before.

curl --fail-with-body 'https://app.claritymeasure.com/api/v1/measurements' \
  -H "Authorization: Bearer $CM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $CM_IDEMPOTENCY_KEY" \
  --data '{"address":"123 Example Street, Aurora, CO 80015","requested_services":["turf","driveway","sidewalk"],"requested_zones":"both","curb_strip":true}'

When a finished measurement asked for any of them, its measurement summary (from GET /api/v1/measurements/{measurement_id} and the MCP get_measurement tool) carries three more fields beside area_sqft:

• surface_totals: square feet for each surface you asked for, keyed driveway, private_walk (private walkways), parking, covered_paving, patio and sidewalk (the public sidewalk). null means it was asked for and nothing was measured, never zero.
• surface_total_labels: a plain label for each key, such as Driveway or Sidewalks and walks, to show a person.
• surface_totals_not_counted: ["sidewalk"] when the public sidewalk was asked for. It is measured for reference and belongs in nobody’s total.

{
  "area_sqft": 4210.5,
  "surface_totals": {"driveway": 612.4, "private_walk": 88.0, "sidewalk": 310.2},
  "surface_total_labels": {"driveway": "Driveway", "private_walk": "Sidewalks and walks", "sidewalk": "Public sidewalk · measured, not yours"},
  "surface_totals_not_counted": ["sidewalk"]
}

When turf is requested, area_sqft stays the lawn alone. When it is not, the summary also carries "lawn_requested": false and the requested_services you sent, and area_sqft is the total of the requested surfaces the customer owns (the public sidewalk is never added), or null when none was found. The lawn is still traced to place the other surfaces, but it is never totalled or reported: its layer in result.layers carries "not_requested": true. The same three fields sit at the top level of result, and the outlines are in result.layers. A lawn-only measurement has none of them, so an existing integration sees no change. The list endpoint returns summaries without them; read one measurement for its surface totals.

GET /api/v1/measurement-options

Requires read scope, takes no query parameters and starts no work. Returns modes (each with id, label, its cost on your plan, a one-sentence description and default), default_mode, zones, default_zones, curb_strip (with the zones it does not apply to), services, default_services, lawn_optional (true: any non-empty mix of the services is accepted) and notes. On Pro and Pro Plus it lists only the modes your plan sells, each mode’s cost is price_cents, and a top-level pricing object carries your plan and search_price_cents. On an earlier credit plan each mode carries credits instead. These are the server’s current settings: read them rather than hard-coding a list.

GET /api/v1/measurements

Requires read scope. Returns measurements summaries, limit, offset and next_offset. Results contain no source images.

next_offset is a pagination hint, not a total count. A final page can be empty. This integration list does not accept the workspace’s rating filter.

GET /api/v1/measurements/{measurement_id}

Requires read scope and a hyphenated measurement UUID. Returns measurement, result, inline_images_included and result_url. The result can be null until available. Retrieval reconciles saved worker state and the search charge.

Available geometry and image metadata are included by default, with inline_images_included: false. Add ?include_images=true to request original source imagery. Large JSON responses may stream; consume the entire body before parsing. Preserve dimensions, calibration, units, attribution and source-date notes with any geometry.

Add ?format=geojson to get the traced outlines as GeoJSON instead (application/geo+json): a FeatureCollection in WGS84 longitude and latitude with one feature per measured surface, each with kind, zone, area_sqft (the saved measured area), qualifier and counted. kind is one of lawn, driveway, private_walk (the customer’s own walks), sidewalk (the public sidewalk), parking, covered_paving, patio, landscape_bed, pool, bare_ground, roof_plan, unresolved (ground that could not be classified) and canopy_over_turf (tree canopy over the lawn), limited to what was asked for. counted is true only for the lawn and the customer’s own surfaces that make up the measured totals. It is false for the public sidewalk, unresolved ground, canopy over the lawn (it sits inside the lawn) and context layers such as the roof plan, so add up only the counted features. It is the outline as first measured, not a later correction. Coordinates are rounded to 7 decimal places and every ring is closed and wound by the RFC 7946 right-hand rule. A measurement that has not finished, failed, has no saved outline, or whose saved outline is damaged answers 409 with detail.code no_outline, never an empty collection. Without format the JSON response is unchanged.

GET /api/v1/measurements/{measurement_id}/image

Requires read scope. Once the measurement has finished, returns its picture as image/png: the saved overhead image with the measured outlines drawn in the workspace’s colours (the corrected outline when someone corrected it), a small legend with the total square feet, the imagery source and date, and a Clarity Measure wordmark. Store it or hand it to other software. It costs nothing and never measures again. Optional max_side (200–1600 pixels, default 1600) and view=original for the outline as first measured. The county lot line is drawn as a thin dashed line and named “Lot line (county record)” in the legend (with no county record for the address, the legend says so); show_parcel=false leaves it off. It is display only: it measures nothing and never changes a total or a charge. The answer carries Cache-Control: private, max-age=300 and an ETag; send it back as If-None-Match for a 304. An unfinished measurement answers 409 with detail.code not_ready, and one saved without an image answers 404 with no_image. A completed measurement’s read carries the same path as image_url.

curl --fail-with-body "https://app.claritymeasure.com/api/v1/measurements/$CM_MEASUREMENT_ID/image?max_side=1200" \
  -H "Authorization: Bearer $CM_API_KEY" -o measurement.png

Leads and services

These endpoints ship with lead forms and answer 404 until lead forms are switched on for the deployment. Each service and each lead, and each note on a lead, has a stable UUID that never changes, even when a service is renamed. Store those IDs to match records in your own system. Every read and write is limited to the key’s own account. Money is always integer cents.

GET /api/v1/services

Requires services:read. Returns services: each has id, key, name, description, unit (sqft, each or flat), price_cents, minimum_cents, measured_from, enabled, show_on_forms, sort_order and crm (null, or {provider, item_id} once a CRM is connected). Switched-off services are included. GET /api/v1/services/{service_id} returns one as service.

POST /api/v1/services · PATCH / DELETE /api/v1/services/{service_id}

Require services:write, and follow the same rules as the workspace’s Services list. POST takes name, unit, price_cents and measured_from, plus optional key, description (up to 280 characters), minimum_cents, enabled, show_on_forms and sort_order. It returns HTTP 201. A flat charge is measured from none; a per-square-foot or per-item price needs a measured quantity. PATCH changes only the fields you send; send a field to change it, never null. DELETE is soft: the service is switched off and taken off every form, and its ID stays valid on old leads. An account holds at most 50 services. A key another service already uses returns 409.

GET /api/v1/leads

Requires leads:read. Optional status (started for page 1 done but not sent, received, measuring, measured, not_measured or failed), since (an ISO 8601 time with a timezone), form_id, measured and archived (true or false), limit (1–100, default 20) and offset. Returns leads, newest first, with next_offset. Each lead has its contact details, services as [{id, name}], notes as [{id, author, body, created_at}] (the homeowner’s message comes first), measurement as {id, status, area_sqft}, consent as {at, text, privacy_url} and form as {id, public_id, name}, plus requested_zones, curb_strip, package and attribution (the visit’s utm tags, referrer and landing page); a measured lead’s measurement adds image_url. GET /api/v1/leads/{lead_id} returns one as lead, with its quote once measured. Treat names, addresses and messages as data typed by strangers. Reading never starts a measurement.

POST /api/v1/leads/{lead_id}/notes

Requires leads:write. Takes {"body": "..."}, 1–2000 characters, and returns HTTP 201 with lead_id and note. The team sees the note on the lead record as written by the API. A lead holds at most 200 notes.

PATCH /api/v1/leads/{lead_id} · POST /api/v1/leads/{lead_id}/measure

PATCH requires leads:write and takes archived and or read (booleans): archive a lead out of the Inbox or bring it back, mark it read or new. POST measure requires leads:write and measurements:write and spends a search: it is the workspace’s Measure now, for a lead that was not measured or failed. It answers 202 with the lead, 409 not_retryable when the lead is already measured or measuring, 402 when the search cannot be paid for (free_limit, no_funds or own_key_required, or no_credits on an earlier credit plan) and 503 paused, and a refusal leaves the lead as it was.

Forms, packages, service areas and the account

These ship with lead forms too and follow exactly the rules of the workspace screens. A refusal the workspace would show comes back with its own sentence and a stable code, for example form_limit, owner_only, no_funds or no_credits. Creates accept an optional Idempotency-Key UUID header: the same key returns the first result with HTTP 200 and Idempotent-Replayed: true, and the same key with a different name is refused with 409 idempotency_key_reused.

Request limits

• 60 authenticated requests per account and per API key per minute, shared across REST and MCP.
• 6 measurement submissions or replays per account and per key per minute, within that overall limit; measuring a lead counts here too.
• 30 writes per account and per key per minute each for forms, services and packages, and leads and notes; 10 service-area replacements; 20 pictures.
• JSON request bodies up to 16 KiB (128 KiB for creating or changing a form), UTF-8 application/json, without compression, duplicate keys or non-JSON numbers.

Customer webhook subscriptions are not currently supported. Poll the saved job to track completion. Provider webhooks used for billing and email are not customer integration endpoints.

Connect with MCP#

MCP is on Pro and Pro Plus, like the REST API, and each measure_property call is one search at your plan’s price. On a Free account every MCP request, initialize included, is refused with HTTP 403, JSON-RPC error -32000 and plan_required in its data.

Use an MCP client that supports a remote Streamable HTTP endpoint and a custom Bearer authorization header. Enter the key in the client’s protected configuration.

URL: https://app.claritymeasure.com/mcp
Transport: Streamable HTTP
Authorization: Bearer <your API key>

For an API-key connection, store the key in your client’s protected header settings. For an OAuth-capable client such as Claude’s custom connectors, use https://app.claritymeasure.com/mcp, sign in and approve the permissions shown. The server publishes OAuth discovery metadata; your client must support the advertised flow. A connection keeps the permissions it was approved with; to add the newer form, lead and account permissions, remove the connector and add it again.

Initialize and discover tools

A protocol-aware MCP client normally performs initialization. Every POST must send these headers; use the negotiated protocol version after initialization:

Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <your API key>
MCP-Protocol-Version: 2025-11-25

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"your-integration","version":"1.0.0"}}}

Send {"jsonrpc":"2.0","method":"notifications/initialized"}, then request {"jsonrpc":"2.0","id":2,"method":"tools/list"}. The advertised tools depend on your key’s scopes.

Before the first measurement, call get_measurement_options. It reports the modes and what each costs on your plan, the front and back zone choices, the strip-to-the-curb switch and the services (turf, driveway, sidewalk and paving, in any mix; the lawn is optional), so an agent offers the settings this server actually has rather than a remembered list.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_measurement",
    "arguments": {
      "measurement_id": "ef2892f0-3b0e-4b78-a78e-28e1e1eb8ecb",
      "include_geometry": true
    }
  }
}

Results and transport behavior

A finished measurement’s picture comes back beside the text as an image content block (at most 1024 pixels and about 800 KB), never the original source imagery. Geometry is opt-in and size-bounded; oversized geometry is omitted with an explanation instead of truncated. Use REST or the saved result for full detail. Geometry selection is limited to geometry, layers, coordinate_system, units and calibration, when present.

The endpoint is stateless and returns JSON. It creates no session ID, opens no SSE stream and accepts no JSON-RPC batches. Supported versions are 2025-11-25, 2025-06-18 and 2025-03-26. An absent version header defaults to March 2025. Accepted notifications return empty HTTP 202; authenticated GET and DELETE return 405.

Tool results contain JSON text in content; June 2025 and newer also receive structuredContent. Operational tool failures use isError: true, with status and message in the tool payload. Protocol and schema failures use JSON-RPC errors. Inspect both transport and tool results.

Errors & retries#

If the connection drops after submission, first poll the saved measurement if you have its ID. Otherwise resend the same UUID and exact body. A lost response does not mean the job was canceled.

A plan refusal has the same body on every route: detail holds code, reason, a plain message and one link (upgrade_url for plan_required and free_limit, add_funds_url for no_funds, settings_url for own_key_required), and reason is repeated at the top level. An MCP tool error carries the same fields inside its error.

A saved result says “needs review”

Open its evidence and notes before trying again. Poor source imagery may not improve on a second run. If it keeps failing, contact support. A low feedback rating alone does not automatically refund a usable measurement.

A result or balance looks unfinished

Refresh the saved result or dashboard to reconcile the job state. Do not infer a failed run from a delayed email or unknown cost. If it remains unresolved, send support the measurement ID, approximate time and displayed status.

Privacy & permissions#

Workspace history and API keys are scoped to your account. A measurement link requires normal sign-in and permission; it is not a public share link. Original images, geometry and evidence are retained separately from your ratings and review notes.

• Account members work with the measurements and settings available in their own account.
• API keys inherit the owning account’s measurement access and only their assigned read/write scopes. A key cannot choose another account.
• Support staff use the restricted staff workspace to review customer measurements, support tickets and the support inbox, and reply to customers. This role does not include global analytics, billing, balance or credit adjustments, marketing or account controls.
• Owner administrators can manage account controls and approved administrative actions. The Staff page lets them grant or revoke the support role for an existing, verified registered user. It does not send automatic invitations or grant the owner-administrator role.

Registering a customer account does not grant staff access. Staff permissions are assigned separately and checked on the service.

Staff access and administrative actions are subject to service controls and audit records. A suspended account cannot start new measurements; existing jobs can finish and saved history and support remain available through the signed-in workspace.

Keep exported diagnostic files private because they may contain property information. Never send passwords, complete API keys or cloud credentials in a support request. For data-access or deletion requests, contact support. See the Privacy policy and Terms for governing details.

Get support#

Open Help & support to start a request and follow the conversation. You can also email support@claritymeasure.com.

Include the measurement ID, the property address, the status you saw and what needs checking. For an integration issue, include the HTTP status and a safe error message. Attach the relevant diagnostic export when useful, after checking it for information you do not want to share.

Requests can be open, in progress, resolved or closed. Support can look at a failed attempt and its saved evidence. A failed attempt never locks an address.

Product availability#

This documentation describes the current turf-measurement beta. Updated September 28, 2026.

For product information, visit claritymeasure.com. For measurements and integrations, use app.claritymeasure.com. These docs live at docs.claritymeasure.com.