Every API here is available over the APIs.io API and to AI agents over MCP.
{
"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 ($9.99 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-2b1
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://artifacts.apis.io/heritagedeed-com/openapi/_original/heritagedeed-com-api-openapi.json