{ "openapi": "3.1.0", "info": { "title": "HeritageDeed AI Title Search API", "version": "1.0.0", "summary": "Order an AI title search or environmental records report for a US property and read the report as JSON and PDF.", "description": "Public-records title search for covered US counties (https://heritagedeed.com/title-search): owner of record, deeds, mortgages matched to releases, liens, lis pendens, court records, tax status and flood zone, as JSON plus a PDF; and environmental records reports for any US address. Reports are paid per report: $49 for a title search and $29 for an environmental report, through a Creem checkout link, or with prepaid API report credits ($25 a title report, packs of 10 for $250). The /v1 endpoints need a free API key (https://heritagedeed.com/developers/api-keys, header Authorization: Bearer) and add batches, signed webhooks, idempotency keys and white-label PDFs, with per-key limits; the keyless /orders endpoints are limited to 10 writes per minute per client. A report is a public-records search, not title insurance or legal advice, and may not be used for any FCRA purpose. AI agents can also use the MCP server at https://heritagedeed.com/mcp/public (docs: https://heritagedeed.com/developers).", "termsOfService": "https://heritagedeed.com/terms", "contact": { "name": "HeritageDeed Team", "url": "https://heritagedeed.com", "email": "support@heritagedeed.com" } }, "servers": [ { "url": "https://heritagedeed.com/api" } ], "externalDocs": { "description": "API documentation, code samples and the MCP server", "url": "https://heritagedeed.com/developers" }, "tags": [ { "name": "orders", "description": "Keyless order endpoints (the website and the MCP server use them)" }, { "name": "API v1", "description": "Orders, batches, webhooks, account" } ], "components": { "schemas": { "AccountPatch": { "properties": { "label": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Label" }, "white_label_name": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ], "title": "White Label Name", "description": "Company name for the PDF cover of reports ordered from now on; '' clears it." }, "default_webhook_url": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Default Webhook Url", "description": "https URL used when an order or batch sets none; '' clears it." } }, "additionalProperties": false, "type": "object", "title": "AccountPatch" }, "CreditsCheckoutIn": { "properties": { "packs": { "type": "integer", "maximum": 20, "minimum": 1, "title": "Packs", "description": "Packs of 10 report credits", "default": 1 } }, "type": "object", "title": "CreditsCheckoutIn" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "KeyConfirmIn": { "properties": { "token": { "type": "string", "maxLength": 200, "minLength": 20, "title": "Token" } }, "type": "object", "required": [ "token" ], "title": "KeyConfirmIn" }, "KeyCreateIn": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "Where the key confirmation (when email is enabled) and report-ready emails go. Use a work address." }, "label": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Label", "description": "A name for the key, e.g. 'production'." }, "company": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Company", "description": "Your company (not shown anywhere public)." }, "use_case": { "type": "string", "maxLength": 1000, "minLength": 10, "title": "Use Case", "description": "What you will use the reports for." }, "accept_terms": { "type": "boolean", "title": "Accept Terms", "description": "You accept the Terms of Service, including the API section: no use for any FCRA purpose." } }, "additionalProperties": false, "type": "object", "required": [ "email", "use_case", "accept_terms" ], "title": "KeyCreateIn" }, "OrderStatus": { "type": "string", "enum": [ "pending", "processing", "complete", "failed", "refunded" ], "title": "OrderStatus" }, "PlanCheckoutIn": { "properties": { "product": { "type": "string", "pattern": "^(pro|pro_reports)$", "title": "Product" } }, "type": "object", "required": [ "product" ], "title": "PlanCheckoutIn" }, "PrecheckIn": { "properties": { "address": { "type": "string", "maxLength": 500, "title": "Address" }, "state": { "type": "string", "maxLength": 20, "title": "State", "default": "" }, "county": { "type": "string", "maxLength": 100, "title": "County", "default": "" }, "report_type": { "type": "string", "title": "Report Type", "default": "current_owner" } }, "additionalProperties": false, "type": "object", "required": [ "address" ], "title": "PrecheckIn" }, "V1OrderIn": { "properties": { "report_type": { "type": "string", "title": "Report Type", "description": "A report type id from GET /v1/report-types.", "default": "current_owner" }, "address": { "type": "string", "maxLength": 500, "title": "Address", "description": "Full street address with house number." }, "state": { "type": "string", "maxLength": 20, "title": "State", "description": "Two-letter state code (title search).", "default": "" }, "county": { "type": "string", "maxLength": 100, "title": "County", "description": "County name without 'County' (title search).", "default": "" }, "parcel_id": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Parcel Id", "description": "Optional parcel id (NYC BBL) if you have it." }, "client_reference": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Client Reference", "description": "Your own id, echoed back everywhere." }, "webhook_url": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Webhook Url", "description": "https URL to POST a signed event to when the order completes or fails. Defaults to the key's default_webhook_url." } }, "additionalProperties": false, "type": "object", "required": [ "address" ], "title": "V1OrderIn", "description": "One order. `state` and `county` are required for a title search and optional for an environmental report.", "examples": [ { "address": "350 5th Ave, New York, NY 10118", "client_reference": "deal-1042", "county": "New York", "report_type": "current_owner", "state": "NY", "webhook_url": "https://example.com/hooks/heritagedeed" } ] }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WatchCheckoutIn": { "properties": { "units": { "type": "integer", "maximum": 100, "minimum": 1, "title": "Units", "description": "Watched properties to pay for ($7 a month each)", "default": 1 } }, "type": "object", "title": "WatchCheckoutIn" }, "WatchIn": { "properties": { "address": { "type": "string", "title": "Address" }, "state": { "type": "string", "title": "State" }, "county": { "type": "string", "title": "County" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" } }, "type": "object", "required": [ "address", "state", "county" ], "title": "WatchIn" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "description": "Your API key: `Authorization: Bearer hd_live_...`", "scheme": "bearer" } } }, "paths": { "/v1": { "get": { "tags": [ "API v1" ], "summary": "API index", "operationId": "index_v1_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/report-types": { "get": { "tags": [ "API v1" ], "summary": "Report types you can order", "description": "Every report type the API accepts, with coverage, price in cents (list_price_cents is the same amount).\nThe list is the website's own list of orderable reports: a new report type appears here automatically.", "operationId": "report_types_v1_report_types_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/coverage": { "get": { "tags": [ "API v1" ], "summary": "Where each report type can be ordered", "description": "Title search: the covered states and counties (exact values to send). Environmental: any US street address.", "operationId": "coverage_v1_coverage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/keys": { "post": { "tags": [ "API v1" ], "summary": "Get a free API key", "description": "Self-service key issuance. When outbound email is configured, a magic link is emailed and the key is shown\nonce on the confirmation page. Otherwise the key is returned in this response, once.", "operationId": "create_key_v1_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyCreateIn" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "202": { "description": "Confirmation link emailed (when outbound email is configured)" }, "409": { "description": "This email already has the maximum number of keys" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Too many keys from this IP address today" } } } }, "/v1/keys/confirm": { "post": { "tags": [ "API v1" ], "summary": "Activate a key from its emailed link", "description": "Exchange the token from the confirmation email for the API key (shown once). Single use, 24 hours.", "operationId": "confirm_key_v1_keys_confirm_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyConfirmIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/account": { "get": { "tags": [ "API v1" ], "summary": "Your key: settings, limits, usage", "operationId": "get_account_v1_account_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "tags": [ "API v1" ], "summary": "Revoke this key (cannot be undone)", "description": "Revokes the key used for this request at once. Orders already placed still finish; their webhooks stop.", "operationId": "revoke_key_v1_account_delete", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } }, "security": [ { "HTTPBearer": [] } ] }, "patch": { "tags": [ "API v1" ], "summary": "Set the white-label name, default webhook or label", "description": "White label: reports ordered after the change show this company name in the brand position of the PDF cover;\nevery page still says 'Prepared by HeritageDeed' and the legal text is unchanged. Name only, no logo.", "operationId": "patch_account_v1_account_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPatch" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/account/webhook-secret": { "post": { "tags": [ "API v1" ], "summary": "Replace the webhook signing secret", "operationId": "rotate_webhook_secret_v1_account_webhook_secret_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/account/usage": { "get": { "tags": [ "API v1" ], "summary": "Daily usage, newest first", "operationId": "usage_v1_account_usage_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 30, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } } } }, "/v1/precheck": { "post": { "tags": [ "API v1" ], "summary": "Match an address to its parcel before ordering", "description": "Runs the county resolvers an order runs first (the environmental report: the Census geocoder). Status:\nmatched, not_found, unavailable (the source is down: an order still works and retries), not_covered or invalid.\nThe owner is not returned.", "operationId": "precheck_v1_precheck_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrecheckIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/orders": { "post": { "tags": [ "API v1" ], "summary": "Order a report", "description": "Creates one order through the same pipeline as the website. The search usually finishes in one to three\nminutes; a county source that is down is retried automatically (up to about 20 minutes) before a report is\ndelivered with the gap named, or the order fails with the reason. Orders are paid per report: the response\ncarries a Creem `checkout_url` and the search starts once it is paid, or the order is paid with a prepaid report credit.", "operationId": "create_order_v1_orders_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Any unique string (UUID): a retried request with the same key returns the same order.", "title": "Idempotency-Key" }, "description": "Any unique string (UUID): a retried request with the same key returns the same order." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1OrderIn" } } } }, "responses": { "200": { "description": "Idempotent replay: the order created earlier with this Idempotency-Key" }, "201": { "description": "Order created; poll it or wait for the webhook", "content": { "application/json": { "schema": {}, "example": { "object": "order", "id": "6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f", "report_type": "current_owner", "report_name": "Current Owner Search", "status": "complete", "payment_status": "free_mode", "address": "350 5th Ave, New York, NY 10118", "state": "NY", "county": "New York", "client_reference": "deal-1042", "white_label_name": "Example Title Co", "created_at": "2026-10-20T14:02:11+00:00", "completed_at": "2026-10-20T14:04:37+00:00", "progress_pct": 100, "quality_pct": 100, "delivery_decision": "deliver", "links": { "self": "https://heritagedeed.com/api/v1/orders/6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f", "report_json": "https://heritagedeed.com/api/v1/orders/6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f/report", "pdf": "https://heritagedeed.com/api/files/6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f/current_owner.pdf", "order_page": "https://heritagedeed.com/order/6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f" }, "webhook": { "url": "https://example.com/hooks/heritagedeed", "status": "delivered", "attempts": 1, "delivered_at": "2026-10-20T14:04:39+00:00" } } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "409": { "description": "Idempotency-Key reused with a different body" }, "422": { "description": "Invalid address, report type, county not covered, or webhook URL" }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } } }, "get": { "tags": [ "API v1" ], "summary": "Your orders, newest first", "operationId": "list_orders_v1_orders_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/OrderStatus" }, { "type": "null" } ], "title": "Status" } }, { "name": "batch_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Batch Id" } }, { "name": "client_reference", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Client Reference" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Cursor: next_created_before of the previous page", "title": "Created Before" }, "description": "Cursor: next_created_before of the previous page" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } } } }, "/v1/orders/{order_id}": { "get": { "tags": [ "API v1" ], "summary": "Order status, progress per source and links", "operationId": "get_order_v1_orders__order_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Order Id" } } ], "responses": { "200": { "description": "The order", "content": { "application/json": { "schema": {}, "example": { "object": "order", "id": "6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f", "report_type": "current_owner", "report_name": "Current Owner Search", "status": "complete", "payment_status": "free_mode", "address": "350 5th Ave, New York, NY 10118", "state": "NY", "county": "New York", "client_reference": "deal-1042", "white_label_name": "Example Title Co", "created_at": "2026-10-20T14:02:11+00:00", "completed_at": "2026-10-20T14:04:37+00:00", "progress_pct": 100, "quality_pct": 100, "delivery_decision": "deliver", "links": { "self": "https://heritagedeed.com/api/v1/orders/6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f", "report_json": "https://heritagedeed.com/api/v1/orders/6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f/report", "pdf": "https://heritagedeed.com/api/files/6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f/current_owner.pdf", "order_page": "https://heritagedeed.com/order/6f1c1f0e-8f5e-4a0e-9a57-2b1f0c3d4e5f" }, "webhook": { "url": "https://example.com/hooks/heritagedeed", "status": "delivered", "attempts": 1, "delivered_at": "2026-10-20T14:04:39+00:00" }, "progress": [ { "source_id": "ny_acris", "status": "success", "timestamp": "2026-10-20T14:03:02+00:00" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "404": { "description": "Not found or not placed with this key" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } } } }, "/v1/orders/{order_id}/report": { "get": { "tags": [ "API v1" ], "summary": "The finished report as JSON", "description": "The same JSON the website stores with the PDF: property, owner of record, risk score and summary, findings,\ndeeds, mortgages with their releases, liens, court records, tax, flood, and every source with its status\n(environmental: each federal list searched, with distances).", "operationId": "get_report_v1_orders__order_id__report_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Order Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "404": { "description": "Not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "425": { "description": "Not complete yet" }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } } } }, "/v1/orders/{order_id}/pdf": { "get": { "tags": [ "API v1" ], "summary": "Redirect to the PDF", "operationId": "get_pdf_v1_orders__order_id__pdf_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Order Id" } } ], "responses": { "302": { "description": "Location: the PDF URL", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "425": { "description": "Not complete yet" }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } } } }, "/v1/batches": { "post": { "tags": [ "API v1" ], "summary": "Order up to 50 reports at once (JSON array or CSV)", "description": "Each row is validated at once (bad rows are rejected with the reason; the others are queued). Queued rows\nbecome orders a few at a time, so a batch never holds up other customers; poll GET /v1/batches/{id}, download\nresults.csv, or set webhook_url for order.completed / order.failed per order and batch.completed at the end.\nAccepted rows count against the key's daily and monthly order quota when the batch is accepted.\nCSV columns: report_type, address, state, county, parcel_id, client_reference (header row required).", "operationId": "create_batch_v1_batches_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "webhook_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "For CSV bodies", "title": "Webhook Url" }, "description": "For CSV bodies" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "responses": { "200": { "description": "Idempotent replay" }, "201": { "description": "Batch accepted: every row is queued or rejected with its reason", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Batches need prepaid report credits" }, "403": { "description": "Key revoked or suspended" }, "413": { "description": "Too many rows" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "orders" ], "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "report_type": { "type": "string" }, "address": { "type": "string" }, "state": { "type": "string" }, "county": { "type": "string" }, "parcel_id": { "type": "string" }, "client_reference": { "type": "string" } }, "required": [ "address" ] } }, "webhook_url": { "type": "string", "format": "uri" } } }, "example": { "orders": [ { "report_type": "current_owner", "address": "350 5th Ave, New York, NY 10118", "state": "NY", "county": "New York", "client_reference": "a-1" }, { "report_type": "environmental", "address": "300 Bond St, Brooklyn, NY 11231", "client_reference": "a-2" } ], "webhook_url": "https://example.com/hooks/heritagedeed" } }, "text/csv": { "schema": { "type": "string" }, "example": "report_type,address,state,county,client_reference\ncurrent_owner,\"350 5th Ave, New York, NY 10118\",NY,New York,a-1\n" }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "webhook_url": { "type": "string" } } } } } } }, "get": { "tags": [ "API v1" ], "summary": "Your batches, newest first", "operationId": "list_batches_v1_batches_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } } } }, "/v1/batches/{batch_id}": { "get": { "tags": [ "API v1" ], "summary": "Batch status with every row", "operationId": "get_batch_v1_batches__batch_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } } } }, "/v1/batches/{batch_id}/results.csv": { "get": { "tags": [ "API v1" ], "summary": "Batch results as CSV", "description": "row, client_reference, report_type, address, state, county, row_status, error, order_id, order_status,\ncompleted_at, pdf_url, report_json_url, order_page.", "operationId": "batch_results_v1_batches__batch_id__results_csv_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } } ], "responses": { "200": { "description": "One line per submitted row", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": {} } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key revoked or suspended" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit or order quota exceeded (Retry-After header on rate limits)" } } } }, "/v1/products": { "get": { "tags": [ "API v1" ], "summary": "Every product with its price", "operationId": "products_v1_products_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/account/credits": { "get": { "tags": [ "API v1" ], "summary": "Report credits, plans and Pro status of this key's account", "operationId": "account_credits_v1_account_credits_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The key's email is not confirmed" } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/credits/checkout": { "post": { "tags": [ "API v1" ], "summary": "Buy report credits (Creem checkout link)", "operationId": "credits_checkout_v1_credits_checkout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsCheckoutIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The key's email is not confirmed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/plans/checkout": { "post": { "tags": [ "API v1" ], "summary": "Start HeritageDeed Pro or Pro Reports (Creem checkout link)", "operationId": "plan_checkout_v1_plans_checkout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanCheckoutIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The key's email is not confirmed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/watches": { "get": { "tags": [ "API v1" ], "summary": "Property Watch: your watched properties and plan", "operationId": "list_watches_v1_watches_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The key's email is not confirmed" } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "API v1" ], "summary": "Property Watch: watch a property", "operationId": "add_watch_v1_watches_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchIn" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The key's email is not confirmed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/watches/{watch_id}": { "get": { "tags": [ "API v1" ], "summary": "Property Watch: one watch with its alerts", "operationId": "get_watch_v1_watches__watch_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "watch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Watch Id" } }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Before" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The key's email is not confirmed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API v1" ], "summary": "Property Watch: stop watching", "operationId": "delete_watch_v1_watches__watch_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "watch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Watch Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The key's email is not confirmed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/watches/checkout": { "post": { "tags": [ "API v1" ], "summary": "Property Watch: pay for more properties (Creem checkout link)", "operationId": "watch_checkout_v1_watches_checkout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchCheckoutIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The key's email is not confirmed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/lists/{list_name}/export.csv": { "get": { "tags": [ "API v1" ], "summary": "Pro: every county of a surplus funds or tax sale list as CSV", "operationId": "list_export_v1_lists__list_name__export_csv_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "list_name", "in": "path", "required": true, "schema": { "type": "string", "title": "List Name" } }, { "name": "history", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "History" } }, { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z]{2}$" }, { "type": "null" } ], "title": "State" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The key's email is not confirmed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders/precheck": { "post": { "tags": [ "orders" ], "operationId": "checkAddress", "summary": "Match an address to its county parcel before ordering", "description": "Runs the county resolvers an order runs first. Returns matched, not_found, unavailable (the county service is down; ordering still works and retries), not_covered or invalid. The owner is not returned.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "example": "350 5th Ave, New York, NY 10118", "description": "Full street address of the property." }, "state": { "type": "string", "enum": [ "NY", "FL", "TX", "IL", "PA", "AZ", "AR", "NC", "SC", "OH", "UT" ], "example": "NY" }, "county": { "type": "string", "example": "New York", "description": "County as the order form names it (for NYC the borough county: New York, Kings, Queens, Bronx, Richmond). See GET /mcp/public tool list_coverage or https://heritagedeed.com/title-search." }, "report_type": { "type": "string", "enum": [ "current_owner", "environmental" ], "default": "current_owner", "description": "environmental: geocode only (any US address); state and county are not needed and come back in the answer." } } } } } }, "responses": { "200": { "description": "Pre-check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "matched", "not_found", "unavailable", "not_covered", "invalid" ] }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests" } } } }, "/orders/": { "post": { "tags": [ "orders" ], "operationId": "orderTitleSearch", "summary": "Order a Current Owner Search (covered counties) or an Environmental Records Report (any US address)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address", "customer_email" ], "properties": { "address": { "type": "string", "example": "350 5th Ave, New York, NY 10118", "description": "Full street address of the property." }, "state": { "type": "string", "enum": [ "NY", "FL", "TX", "IL", "PA", "AZ", "AR", "NC", "SC", "OH", "UT" ], "example": "NY" }, "county": { "type": "string", "example": "New York", "description": "County as the order form names it (for NYC the borough county: New York, Kings, Queens, Bronx, Richmond). See GET /mcp/public tool list_coverage or https://heritagedeed.com/title-search." }, "report_type": { "type": "string", "enum": [ "current_owner", "environmental" ], "default": "current_owner", "description": "current_owner needs state and county (a covered county). environmental takes any US street address; its state and county are determined from the address. It is a records search, not a Phase I Environmental Site Assessment." }, "customer_email": { "type": "string", "format": "email", "description": "Where the report link is sent." } } } } } }, "responses": { "201": { "description": "Order created", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "checkout_url": { "type": [ "string", "null" ], "description": "Creem checkout link to pay for the report; null when the order is covered by prepaid report credits." } } } } } }, "422": { "description": "Invalid request or county not covered" }, "429": { "description": "Too many requests" } } } }, "/tools/superfund-sites": { "post": { "tags": [ "orders" ], "operationId": "superfundSitesNear", "summary": "Free lookup: nearest EPA Superfund (NPL) sites to a US address", "description": "NPL sites within 3 miles with status and distance, the number of other Superfund sites within 1 mile and of EPA-regulated facilities within 0.5 mile. Limited to 20 lookups an hour per client.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "example": "300 Bond St, Brooklyn, NY 11231" } } } } } }, "responses": { "200": { "description": "Lookup result" }, "422": { "description": "Address not found as a US street address" }, "429": { "description": "Too many requests" }, "503": { "description": "A government service did not answer" } } } }, "/orders/{order_id}": { "get": { "tags": [ "orders" ], "operationId": "getOrderStatus", "summary": "Order status, per-source progress and the PDF link once complete", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Status (pending, processing, complete, failed) with progress per source" }, "404": { "description": "Not found" } } } }, "/orders/{order_id}/data": { "get": { "tags": [ "orders" ], "operationId": "getReport", "summary": "The finished report as structured JSON", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Report JSON: property, owner, risk score and summary, findings, chain counts, tax, flood, sources and their status" }, "404": { "description": "Not found" }, "425": { "description": "Not complete yet" } } } }, "/coverage": { "get": { "operationId": "getCoverage", "summary": "Where every product works: title search counties (with city aliases), building records cities, property history places, surplus and tax sale counties, calculator states", "responses": { "200": { "description": "Coverage per product; title_search.states[].counties[].county is the value to order with" } } } }, "/tools/title-premium": { "post": { "operationId": "titleInsurancePremium", "summary": "Free calculator: title insurance premiums from the promulgated or filed rate schedule (TX, FL, PA, NY)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "tx", "fl", "pa", "ny" ] }, "owner_amount": { "type": "number", "example": 400000 }, "loan_amount": { "type": "number", "example": 320000 }, "ny_zone": { "type": "integer", "enum": [ 1, 2 ] }, "ny_county": { "type": "string", "example": "Erie" }, "pa_homeowner": { "type": "boolean" }, "fl_prior_policy": { "type": "number" } } } } } }, "responses": { "200": { "description": "owner, loan, fees, total, lines with their rule, notes, schedule (effective date) and sources. An estimate." }, "422": { "description": "Invalid input" } } } }, "/tools/transfer-tax": { "post": { "operationId": "transferTax", "summary": "Free calculator: real estate transfer taxes (nyc, ny, fl, philadelphia, chicago, cook, nc, sc, ar, tx, az)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "place", "price" ], "properties": { "place": { "type": "string", "enum": [ "nyc", "ny", "fl", "philadelphia", "chicago", "cook", "nc", "sc", "ar", "tx", "az" ] }, "price": { "type": "number", "example": 1200000 }, "kind": { "type": "string", "enum": [ "residential", "other" ], "default": "residential" }, "mortgage": { "type": "number", "description": "Florida only: new mortgage amount" } } } } } }, "responses": { "200": { "description": "Each tax with amount and customary payer, total, flags and sources. An estimate." }, "422": { "description": "Invalid input" } } } }, "/tools/net-sheet": { "post": { "operationId": "sellerNetSheet", "summary": "Free calculator: seller net proceeds and buyer closing costs (fl, tx, nyc, ny, philadelphia)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "place", "price" ], "properties": { "place": { "type": "string", "enum": [ "fl", "tx", "nyc", "ny", "philadelphia" ] }, "price": { "type": "number", "example": 400000 }, "payoff": { "type": "number" }, "commission_pct": { "type": "number", "example": 5.5 }, "loan_amount": { "type": "number" }, "owner_policy_payer": { "type": "string", "enum": [ "seller", "buyer" ] }, "seller_share_of_split_tax": { "type": "number", "minimum": 0, "maximum": 1 }, "kind": { "type": "string", "enum": [ "residential", "other" ] }, "ny_county": { "type": "string" }, "recording_pages": { "type": "number" }, "recording_amount": { "type": "number" }, "other_seller_costs": { "type": "number" }, "fl_prior_policy": { "type": "number" } } } } } }, "responses": { "200": { "description": "Seller lines, seller costs, net, buyer lines, buyer costs, flags and sources. An estimate." }, "422": { "description": "Invalid input" } } } } } }