{
  "openapi": "3.0.3",
  "info": {
    "title": "Ava Data API",
    "version": "1.2.2",
    "description": "Ava Data's REST API for skip tracing (Deep Search, Standard Search and bulk CSV files), Digital Matching (ad-platform audience files) and List Builder (property lists). Use it from your CRM, AI agents or your own software.\n\nBase URL: https://app.avadata.ai/api/v1. Every path in this file is relative to it, so POST /deep-search is https://app.avadata.ai/api/v1/deep-search. This file is served without a key at GET /openapi.json as a file download with no CORS headers, so browser-based tools can't import it by URL: download it and import the file.\n\nBefore you start: you need an active or trialing plan (searches, uploads and List Builder previews, pulls and skip traces return 403 with code SUBSCRIPTION_REQUIRED otherwise, even with wallet credits), an API key from Settings → API Access, and available credits. Call the API from your server: it sends no CORS headers, so requests from a web page fail, and a key must never be shipped to a browser. Send the key exactly as `Authorization: Bearer sk_live_...`. JSON requests need `Content-Type: application/json` and a body of at most 1 MB (413 with code BODY_TOO_LARGE). CSV uploads are multipart/form-data with the file in a field named `file`, up to 100 MB (413 with code FILE_TOO_LARGE).\n\nNo test mode: there is no sandbox and no test key. Every call runs against live data and spends real credits. The cheapest real test: GET /credits (free) confirms your key works, POST /lists/preview is free, and a few Standard Searches with `dataTypes` set to [\"phone\"] on records you already know cost 1 credit per match and nothing when there's no match.\n\nBilling. Read `creditsCharged` in each response rather than computing it from `matchFound`.\n- Deep Search: 10 credits when the result includes at least one phone, email or related person. A match that returns only an address or identity costs 0, and so does no match. The search needs 10 available credits to start.\n- Standard Search: on a match, 1 credit for each data type in `dataTypes`, even when that type comes back empty. No match costs 0. List each data type once: a repeated type is charged again.\n- Bulk uploads and list skip traces: credits are reserved up front (rows × data types). When the job finishes, each row is charged 1 credit for each requested data type actually returned, and the rest is released.\n- Digital Matching: `creditsPerMatch` credits for each matched contact, every selected platform included. Every uploaded row is reserved up front.\n- List Builder: 1 credit per property record pulled into a list. The filter catalog, previews, reading records and downloading a list are free.\n\nCredits: `availableCredits` on GET /credits (total minus reserved) is what you can spend. `reservedCredits` are held by running bulk jobs, Digital Matching jobs, list pulls and skip traces until they finish. Subscription credits are spent before wallet credits.\n\nErrors: every error body is JSON `{\"success\": false, \"error\": \"...\"}`, sometimes with `code`, `field` or extra fields (see the Error schema). Many errors carry no `code` (every 401, search 402s and most upload 400s), so branch on the HTTP status first and use `code`, when present, to tell cases apart. A 500 from a search refunds the credits it took and is safe to retry after a short wait.\n\nRate limit: 60 requests per API key in a fixed 60-second window that starts with the key's first request. Every request made with the key counts, including errors, status polls and downloads; GET /openapi.json and requests refused before the key is checked (401s, INVALID_JSON, BODY_TOO_LARGE and unknown paths) don't. Every other response carries X-RateLimit-Limit (60), X-RateLimit-Remaining (requests left in this window) and X-RateLimit-Reset (when the window resets, as a Unix timestamp in seconds). Request 61 gets 429 with code RATE_LIMITED, a Retry-After header (whole seconds until the window resets, at least 1) and `retryAfter`, `limit` and `resetsAt` in the body: wait Retry-After seconds, then retry. Counts are kept per server instance, so treat X-RateLimit-Remaining as a guide and always honor Retry-After. List Builder also has per-account limits; their 429s carry their own codes, some send Retry-After, and the X-RateLimit-* headers don't describe them.\n\nRetries and timeouts: searches and CSV uploads accept no idempotency key, so retrying a request that timed out on your side can charge a second search or start a second job. Before retrying one, compare `availableCredits` and `reservedCredits` on GET /credits with the values from before the request. POST /lists and POST /lists/{listId}/skip-trace accept an `Idempotency-Key` header. A search can wait up to a minute before it runs when the service is busy, so give searches a client timeout of at least 90 seconds.\n\nJobs: bulk, Digital Matching and list jobs run in the background. Poll their status every 5-10 seconds (each poll counts toward the rate limit); there are no webhooks or callbacks. Bulk and Digital Matching results stay downloadable until the job is deleted from History in the app.\n\nVersioning: changes within /api/v1 are additive. New endpoints, optional request fields, response fields, error codes and enum values can appear at any time, so ignore fields and codes you don't recognize. A change that could break an existing integration is announced at least 30 days ahead.\n\nChanges in 1.2.2: county lists match each county by its Census county code instead of by name. Requests and responses keep their shape, but counts can change: an independent city such as Baltimore city now finds its homes, and a county that shares its name (Baltimore County) counts only its own. Connecticut county lists use its 8 counties (Fairfield, Hartford, Litchfield, Middlesex, New Haven, New London, Tolland and Windham) instead of the 9 planning regions. GET /lists and GET /lists/{listId} can show lists made in the app from street addresses or a map area; their `filters.location.kind` is address, radius or polygon (see ListResource `filters`), and lists made in the app can also show `ranges.estimatedValue` (the estimated home value, in dollars). POST /lists and POST /lists/preview don't take those kinds or `ranges.estimatedValue` yet and answer 400.\n\nChanges in 1.2.1: the per-key 429 now sends a Retry-After header, code RATE_LIMITED and `retryAfter`, `limit` and `resetsAt` in the body, and its error text says how long to wait. Every response to a request whose key is accepted, errors included, carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.\n\nChanges in 1.2.0: added the List Builder endpoints (/lists), `layout=standard` on GET /bulk/{jobId}/download, the `Idempotency-Key` header on the two List Builder POSTs, and the 409 and 503 responses. Documented the 413 responses, the error codes and the request limits. Corrected the documented Deep Search and Standard Search response fields (phones, emails, addresses, name) and the bulk CSV input rules to match what the API already returns and accepts; those endpoints behave as before. Response `data` objects are now named schemas (for example DeepSearchResult, StandardSearchResult and BulkJobStatus), so generated clients get readable type names; the JSON is unchanged.\n\nSupport: Support@avadata.ai. Responses carry no request ID, so include the endpoint, the time (UTC) and the HTTP status when you write in.\n\nPermitted use: see section 3 of the Terms of Service (https://avadata.ai/terms/). Ava Data is not a consumer reporting agency, and the information it provides is not a consumer report under the Fair Credit Reporting Act. You may not use it to establish eligibility for credit or insurance, employment, housing or tenancy, a government licence or benefit, or any other purpose regulated by the FCRA. Ava Data does not screen numbers against do-not-call registries, and responses have no do-not-call or consent field. You are solely responsible for complying with the TCPA, federal and state do-not-call rules and every other law that governs contacting people, including obtaining any consent those laws require.",
    "termsOfService": "https://avadata.ai/terms/",
    "contact": {
      "name": "Ava Data Support",
      "email": "Support@avadata.ai"
    }
  },
  "servers": [
    {
      "url": "https://app.avadata.ai/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Search",
      "description": "Single-record skip trace searches. The result comes back in the response."
    },
    {
      "name": "Bulk",
      "description": "Skip trace a CSV file as a background job: upload, poll the status, then download the results with layout=standard."
    },
    {
      "name": "Digital Matching",
      "description": "Turn a contact CSV into ready-to-upload customer-list files for major ad platforms. Each platform's file holds hashed identifiers in that platform's format. Uploads return 403 when Digital Matching is turned off for the account."
    },
    {
      "name": "List Builder",
      "description": "Build property lists from the same filters as the List Builder page: area, property type, owner type, quick lists (distress and equity signals), timing and ranges. Lists run as background jobs: create, poll, then read or download the records."
    },
    {
      "name": "Account",
      "description": "Credit balance and API usage."
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/deep-search": {
      "post": {
        "tags": [
          "Search"
        ],
        "summary": "Deep Search",
        "operationId": "deepSearch",
        "description": "Looks up one person by name and returns their phones, emails and addresses, plus related people (relatives and associates) with their phone numbers.\n\nInput: only `lastName` is validated as required, but a last name on its own can match too many people. Send `firstName` with a ZIP code, or with a city and state, and the street address when you have it. A search that matches too many people returns 400 with code INSUFFICIENT_INPUT (credits refunded). Deep Search looks up people: a company, LLC or trust name sent as `lastName` usually finds no match, so send an owner's personal name. Fields that aren't in the schema are ignored, not refused, so check the spelling (`firstName`, not `first_name`). Validation errors name only the first problem and have no `field`: a missing `lastName`, or a body sent without `Content-Type: application/json`, returns 400 \"Required\".\n\nCost: 10 credits, taken when the search starts (402 when fewer than 10 are available) and refunded unless the result includes at least one phone, email or related person. So `matchFound: true` with `creditsCharged: 0` is a normal result. A 500 refunds the credits and is safe to retry after a short wait.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeepSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search completed. Check `matchFound` for a match and `creditsCharged` for the charge (10 or 0).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeepSearchResponse"
                },
                "examples": {
                  "match": {
                    "summary": "Match with contact data (10 credits)",
                    "value": {
                      "success": true,
                      "data": {
                        "matchFound": true,
                        "subject": {
                          "firstName": "John",
                          "lastName": "Smith",
                          "aliases": [
                            "John A Smith"
                          ],
                          "age": 45,
                          "deceased": false,
                          "phones": [
                            {
                              "number": "5125551234",
                              "lineType": "Mobile",
                              "disconnected": false
                            },
                            {
                              "number": "5125559876",
                              "lineType": "Landline",
                              "disconnected": false
                            }
                          ],
                          "emails": [
                            "john.smith@example.com"
                          ],
                          "addresses": [
                            {
                              "address": "123 Main St",
                              "city": "Austin",
                              "state": "TX",
                              "zip": "78701-1234"
                            }
                          ],
                          "bankruptcy": false
                        },
                        "relatedPeople": [
                          {
                            "firstName": "Jane",
                            "lastName": "Smith",
                            "age": 43,
                            "deceased": false,
                            "relationship": "Spouse",
                            "phones": [
                              {
                                "number": "5125554321",
                                "lineType": "Mobile",
                                "disconnected": false
                              }
                            ],
                            "emails": [],
                            "addresses": [],
                            "bankruptcy": false
                          }
                        ],
                        "creditsCharged": 10
                      }
                    }
                  },
                  "matchWithoutContactData": {
                    "summary": "Match with no phone, email or related person (free)",
                    "value": {
                      "success": true,
                      "data": {
                        "matchFound": true,
                        "subject": {
                          "firstName": "John",
                          "lastName": "Smith",
                          "deceased": false,
                          "phones": [],
                          "emails": [],
                          "addresses": [
                            {
                              "address": "123 Main St",
                              "city": "Austin",
                              "state": "TX",
                              "zip": "78701"
                            }
                          ],
                          "bankruptcy": false
                        },
                        "relatedPeople": [],
                        "creditsCharged": 0
                      }
                    }
                  },
                  "noMatch": {
                    "summary": "No match (free)",
                    "value": {
                      "success": true,
                      "data": {
                        "matchFound": false,
                        "creditsCharged": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/standard-search": {
      "post": {
        "tags": [
          "Search"
        ],
        "summary": "Standard Search",
        "operationId": "standardSearch",
        "description": "Looks up one person by name and address and returns phones, emails or both, chosen with `dataTypes`.\n\nInput: `lastName` and `dataTypes` are the only fields validated as required, but the search needs a name and a complete address: street plus ZIP, or city and state. When the details are too incomplete for the search to run, the call returns 400 with code INSUFFICIENT_INPUT (credits refunded). Fields that aren't in the schema are ignored, not refused. Validation errors name only the first problem and have no `field`: a missing `lastName` or `dataTypes`, or a body sent without `Content-Type: application/json`, returns 400 \"Required\".\n\nCost: on a match, 1 credit for each type in `dataTypes` ([\"phone\"] or [\"email\"] = 1, [\"phone\",\"email\"] = 2), charged even when a requested type comes back empty. No match costs 0. List each type once: the API doesn't remove repeats, so [\"phone\",\"phone\"] is charged 2 credits on a match. The credits are taken when the search starts (402 when not enough are available). A 500 refunds them and is safe to retry after a short wait.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StandardSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search completed. Check `matchFound` for a match and `creditsCharged` for the charge.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardSearchResponse"
                },
                "examples": {
                  "match": {
                    "summary": "Match with dataTypes [\"phone\",\"email\"] (2 credits)",
                    "value": {
                      "success": true,
                      "data": {
                        "matchFound": true,
                        "phones": [
                          {
                            "number": "5125551234",
                            "lineType": "Mobile"
                          },
                          {
                            "number": "5125559876",
                            "lineType": "Landline"
                          }
                        ],
                        "emails": [
                          "john.smith@example.com"
                        ],
                        "name": {
                          "first": "John",
                          "last": "Smith"
                        },
                        "addresses": [
                          {
                            "address": "123 Main St",
                            "city": "Austin",
                            "state": "TX",
                            "zip": "78701",
                            "zip4": "1234"
                          }
                        ],
                        "matchType": "Individual",
                        "creditsCharged": 2
                      }
                    }
                  },
                  "matchWithEmptyType": {
                    "summary": "Match where no email came back: still 2 credits for [\"phone\",\"email\"]",
                    "value": {
                      "success": true,
                      "data": {
                        "matchFound": true,
                        "phones": [
                          {
                            "number": "5125551234",
                            "lineType": "Mobile"
                          }
                        ],
                        "emails": [],
                        "name": {
                          "first": "John",
                          "last": "Smith"
                        },
                        "addresses": [
                          {
                            "address": "123 Main St",
                            "city": "Austin",
                            "state": "TX",
                            "zip": "78701"
                          }
                        ],
                        "matchType": "Household",
                        "creditsCharged": 2
                      }
                    }
                  },
                  "noMatch": {
                    "summary": "No match (free)",
                    "value": {
                      "success": true,
                      "data": {
                        "matchFound": false,
                        "creditsCharged": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/bulk/upload": {
      "post": {
        "tags": [
          "Bulk"
        ],
        "summary": "Upload CSV for bulk processing",
        "operationId": "bulkUpload",
        "description": "Upload a CSV of people to skip trace for phones, emails or both as a background job. Returns a `jobId`: poll GET /bulk/{jobId}/status, then download with GET /bulk/{jobId}/download?layout=standard.\n\nFile: the CSV goes in a multipart field named `file` (100 MB maximum; larger files return 413 with code FILE_TOO_LARGE, and any other multipart problem returns 400 with code INVALID_UPLOAD; a request that isn't multipart, or has no file part, returns 400 \"CSV file is required...\" with no code). It is read as UTF-8 (from Excel, save as CSV UTF-8; other encodings garble accented names), and the first line must be the header row. Rows are split on line breaks before quotes are read, so remove line breaks inside cells (for example two-line addresses) first. Blank lines are ignored. Up to 250,000 data rows per file, counting rows that are later skipped. A larger file returns 400 with `maxBatchSize` and `recordCount`; rely on `maxBatchSize`, since the cap can change.\n\nColumns: headers are matched case-insensitively, ignoring surrounding spaces, against these exact names. Other headers, such as first_name, zip_code or address1, aren't used for searching (column mapping is a feature of the app's upload screen, not the API). If two columns match the same field, the first is used.\n- Street address: address, street, street address\n- First name: first name, firstname, first\n- Last name: last name, lastname, last\n- Full name, used only when the file has no first-name or no last-name column: name, full name, fullname, owner name, owner\n- City: city\n- State: state, st\n- ZIP: zip, zipcode, zip code, postal code\n\nRows: each row needs one of these combinations to be searched: First + Last Name + ZIP; First + Last Name + City + State; or Street Address + City + State + ZIP. A full-name value counts as First + Last Name, except company names (LLC, Inc. and similar), which need the full street address, city, state and ZIP. A file whose columns can't meet any combination returns 400 (\"The CSV columns can't produce any matches.\"), so an address column on its own is not enough. Rows that meet none are skipped: they aren't searched, reserved or charged, and the response reports them in `skippedCount` and `skippedReason`. If no row qualifies, the call returns 400 with `invalidCount`.\n\nJoining results: results hold only the rows that were searched, with your own columns first, and carry no row number. Add an ID column of your own (any header not listed above) so you can join results back to your data. `recordCount` is the number of rows searched: the data rows minus `skippedCount`.\n\nCost: `recordCount` × `creditsPerMatch` credits are reserved now (402 with `needed`, `available`, `reserved` and `total` when they aren't available). When the job finishes, each row is charged 1 credit for each requested data type actually returned (with [\"phone\",\"email\"], a row that returns a phone but no email costs 1), and the rest of the reservation is released. List each data type once: a repeated type isn't charged twice at the end, but it is counted twice in the reservation and in `creditsPerMatch`.\n\nRetries: there is no idempotency key, so retrying an upload creates a second job and a second reservation. If an upload times out, check `reservedCredits` on GET /credits before you send it again.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file",
                  "dataTypes"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The CSV file: UTF-8, a header row, then at least one data row. For example:\nContact ID,First Name,Last Name,Address,City,State,Zip\nC-1001,John,Smith,123 Main St,Austin,TX,78701",
                    "example": "leads.csv"
                  },
                  "dataTypes": {
                    "type": "string",
                    "description": "JSON array string of the data to append: [\"phone\"], [\"email\"] or [\"phone\",\"email\"]. List each type once.",
                    "example": "[\"phone\",\"email\"]"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job created and processing started.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkUploadResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/bulk/{jobId}/status": {
      "get": {
        "tags": [
          "Bulk"
        ],
        "summary": "Check bulk job status",
        "operationId": "bulkStatus",
        "description": "Poll a bulk job (a CSV upload or a list skip trace) every 5-10 seconds; each poll counts toward the 60-per-minute limit, and there are no webhooks. `status` moves through uploading, queued and processing to completed or failed. Once it is completed, download with GET /bulk/{jobId}/download?layout=standard; the final charge is `creditsCharged` in that response (this one doesn't include it).\n\n`failed` is usually final. Once processing has started, a problem on our side doesn't fail a job: it stays in progress (a status other than completed or failed), with its credits still reserved, until processing ends. Rarely, a job that reported `failed` turns out to be still processing or already finished: it moves back to processing (its credits are reserved again) or to completed, and its matches are charged like any other job, whether or not you keep checking. So check the status once more before you upload the same file again. A status check can take a few seconds when it is the one that finds this out.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The job ID returned by the bulk upload endpoint or by POST /lists/{listId}/skip-trace."
          }
        ],
        "responses": {
          "200": {
            "description": "Current job status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkStatusResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/bulk/{jobId}/download": {
      "get": {
        "tags": [
          "Bulk"
        ],
        "summary": "Download bulk job results",
        "operationId": "bulkDownload",
        "description": "Download the results of a completed bulk job as JSON (default) or CSV. Send `layout=standard` on every download. The job must be `completed` (otherwise 400 \"Job is not completed yet. Current status: ...\"). Results stay available until the job is deleted from History in the app; after that the job no longer exists and the call returns 404 \"Job not found\". 400 \"No results available for download\" means a completed job has no stored results. Rows skipped at upload are not in the results.\n\nStandard layout: results of a list skip trace (POST /lists/{listId}/skip-trace) always use the standard layout, and `layout=standard` gives any bulk job the same layout. Each row has your own columns first, in their original order (for POST /lists/{listId}/skip-trace: Owner Name, Owner 1 First Name, Owner 1 Last Name, Owner 2 First Name, Owner 2 Last Name, Mailing Address, Mailing City, Mailing State, Mailing Zip, Property Address, Property City, Property State, Property Zip and Property ID, so you can join results back to the list), then these result columns:\n- `Match Found`: Yes or No.\n- `Phone 1` to `Phone 6`, each followed by `Line Type 1` to `Line Type 6` (for example Mobile or Landline).\n- `Mobile 1` to `Mobile 3` and `Landline 1` to `Landline 3`: the same numbers grouped by line type.\n- `Email 1`, `Email 2` and so on, when email was requested.\n\nEmpty values are empty strings. In JSON, `results` is an array of row objects keyed by column name and `columns` lists the column names in order. In CSV, the header row uses the same names, and cells that start with =, +, @ (or - when the value isn't a number) get a leading ' so spreadsheets don't run them as formulas. If one of your columns has the same name as another column, a number is added to it, like `Phone 1 (2)`, and a blank column name becomes `Column N` (N is its position).\n\nWithout `layout=standard`, CSV upload jobs keep their original response shape, where `results` is usually the results file as one CSV text string in a different column layout. It is kept only so existing integrations don't break; use `layout=standard` for every integration. Digital Matching jobs aren't available in the standard layout (404); download them with GET /audience/{jobId}/download.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The job ID returned by the bulk upload endpoint or by POST /lists/{listId}/skip-trace."
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            },
            "description": "Response format: `json` (the default) or `csv`, in lower case. Any value other than `csv` returns JSON."
          },
          {
            "name": "layout",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "standard"
              ]
            },
            "example": "standard",
            "description": "Send `standard` (recommended for every integration) for the standard layout described above. List skip-trace results always use it, with or without this parameter. Any other value returns 400 with `field: layout`."
          }
        ],
        "responses": {
          "200": {
            "description": "Completed job results.",
            "headers": {
              "Content-Disposition": {
                "description": "Sent with format=csv: attachment; filename=\"bulk_results_{jobId}.csv\".",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=\"bulk_results_abc123-def456.csv\""
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkDownloadResponse"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/audience/upload": {
      "post": {
        "tags": [
          "Digital Matching"
        ],
        "summary": "Upload CSV to build ad audiences",
        "operationId": "audienceUpload",
        "description": "Upload a contact CSV and receive ready-to-upload customer-list files for the selected ad platforms. Each contact is matched against Ava Data's identity graph, and each match gets hashed identifiers in each platform's format (often several emails and phone numbers per person). Returns a `jobId`: poll GET /audience/{jobId}/status, then download with GET /audience/{jobId}/download.\n\nAccess: Digital Matching must be turned on for the account; otherwise the call returns 403 \"Digital Matching access is not enabled for this account\" (no code).\n\nFile: the CSV goes in a multipart field named `file` (100 MB maximum; larger files return 413 with code FILE_TOO_LARGE, and any other multipart problem returns 400 with code INVALID_UPLOAD; a request that isn't multipart, or has no file part, returns 400 \"CSV file is required...\" with no code). It is read as UTF-8 (from Excel, save as CSV UTF-8; other encodings garble accented names), and the first line must be the header row. Rows are split on line breaks before quotes are read, so remove line breaks inside cells (for example two-line addresses) first. Blank lines are ignored. Up to 50,000 data rows per file. A larger file returns 400 with `maxBatchSize` and `recordCount`; rely on `maxBatchSize`, since the cap can change.\n\nColumns: headers are matched case-insensitively, ignoring surrounding spaces, against these exact names; other headers aren't used for matching.\n- Email: email, e-mail, email address, emailaddress\n- Phone: phone, phone number, phonenumber, mobile, cell, cell phone\n- Street address: address, street, street address\n- First name: first name, firstname, first\n- Last name: last name, lastname, last\n- Full name, used only when the file has neither a first-name nor a last-name column: full name, fullname, name, owner name, owner\n- City: city\n- State: state, st\n- ZIP: zip, zipcode, zip code, postal code\n\nThe columns must allow at least one of: email; phone; street + city + state + ZIP; name + city + state; or name + ZIP, where name is first and last name columns or a full-name column. Otherwise the call returns 400. Rows aren't checked one by one at upload: every data row counts in `recordCount` and is reserved, and rows that can't be matched are never charged.\n\nCost: `creditsPerMatch` credits for each matched contact, every selected platform included. Read the price from `creditsPerMatch` in the response rather than hard-coding it. `recordCount` × `creditsPerMatch` credits are reserved now (402 with `needed`, `available`, `reserved` and `total` when they aren't available); when the job finishes, matched contacts are charged and the rest is released. There is no idempotency key, so retrying an upload creates a second job.\n\nBy uploading you confirm you have the right to use the list for advertising and will follow each ad platform's customer-list policies.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file",
                  "platforms"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The CSV file: UTF-8, a header row, then at least one data row.",
                    "example": "contacts.csv"
                  },
                  "platforms": {
                    "type": "string",
                    "description": "JSON array string of one or more target platforms: \"facebook\", \"google\", \"linkedin\", \"tiktok\", \"generic\". Repeats are removed.",
                    "example": "[\"facebook\",\"google\"]"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job created and processing started.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudienceUploadResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/audience/{jobId}/status": {
      "get": {
        "tags": [
          "Digital Matching"
        ],
        "summary": "Check Digital Matching job status",
        "operationId": "audienceStatus",
        "description": "Poll a Digital Matching job every 5-10 seconds; each poll counts toward the 60-per-minute limit, and there are no webhooks. Only Digital Matching job IDs work here (404 for other jobs). There is no time estimate. `creditsCharged` and `platformCounts` are final once `status` is completed. As with bulk jobs, a job that reported `failed` can, rarely, move back to processing (its credits are reserved again) or to completed, so check the status once more before you upload the same file again.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The job ID returned by the audience upload endpoint."
          }
        ],
        "responses": {
          "200": {
            "description": "Current job status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudienceStatusResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/audience/{jobId}/download": {
      "get": {
        "tags": [
          "Digital Matching"
        ],
        "summary": "Download audience files",
        "operationId": "audienceDownload",
        "description": "Download a completed Digital Matching job (otherwise 400 \"Job is not completed yet\"). By default you get a ZIP named digital_matching_{jobId}.zip that holds:\n- One CSV per selected platform, with the identifiers hashed (SHA-256) in that platform's format: facebook_instagram_custom_audience.csv, google_ads_customer_match.csv, linkedin_contact_list.csv, tiktok_customer_file.csv and generic_hashed_audience.csv. A platform with no matched contacts has no file in the ZIP.\n- master_audience_data.csv: your contacts as you uploaded them, with every appended identifier. Keep it for reference and auditing; it isn't meant for upload.\n- README.txt: how to upload each file.\n\nPass `platform` to download one platform's CSV instead. It must be one of the job's platforms (400 \"Unknown platform for this job\" otherwise), and a platform with no matched contacts returns 200 with an empty body. Results stay available until the job is deleted from History in the app; after that the job no longer exists and the call returns 404 \"Job not found\".",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The job ID returned by the audience upload endpoint."
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "facebook",
                "google",
                "linkedin",
                "tiktok",
                "generic"
              ]
            },
            "description": "Download one of the job's platform CSVs instead of the full ZIP."
          }
        ],
        "responses": {
          "200": {
            "description": "Audience files (ZIP) or a single platform CSV.",
            "headers": {
              "Content-Disposition": {
                "description": "attachment; filename=\"digital_matching_{jobId}.zip\" for the ZIP, or the platform file name (for example google_ads_customer_match.csv) with `platform`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=\"digital_matching_abc123-def456.zip\""
              }
            },
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/lists/filters": {
      "get": {
        "tags": [
          "List Builder"
        ],
        "summary": "Get filter options",
        "operationId": "getListFilters",
        "description": "Returns every value the List Builder `filters` object accepts: location types and states, quick lists (with the timing windows each one owns), owner, property, loan and lien types, timing presets, Probate & Death Records options, range fields, and the record columns you can request. Use the ids from this catalog in `filters` and `columns`. Free. Returns 403 when List Builder isn't turned on for the account.",
        "responses": {
          "200": {
            "description": "The filter catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListFiltersResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/lists/preview": {
      "post": {
        "tags": [
          "List Builder"
        ],
        "summary": "Preview a list",
        "operationId": "previewList",
        "description": "Counts the properties that match your filters and shows what a pull would cost, without pulling or charging anything. Send the same `filters` you plan to send to POST /lists. Previews are free, but they share the account's limit of 20 per minute with the List Builder page (429 with code `PREVIEW_MINUTE_LIMIT` and a `Retry-After: 60` header) and are capped at 250 per account per UTC day (429 with code `PREVIEW_DAILY_LIMIT`, plus `limit`, `resetsAt` and a `Retry-After` header in seconds). Invalid filters return 400 with `field` naming the bad path, for example `filters.location.state`. If a match count can't be fetched, the call returns 503 with code `PREVIEW_UNAVAILABLE`; try again.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Match count and cost estimate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/lists": {
      "post": {
        "tags": [
          "List Builder"
        ],
        "summary": "Create a list",
        "operationId": "createList",
        "description": "Starts a list pull in the background and returns the list with status `processing`. `maxRecords` credits (1 per record) are reserved when the list is created. When the pull finishes you are charged for the records actually pulled and the rest is released; a pull that stops early keeps, and charges, the records it already pulled. Tip: preview first and set `maxRecords` to the preview's `recordsToPull` so you only hold the credits you need. Poll GET /lists/{listId} until `status` is `completed` or `failed`. An account can have 5 lists pulling at once (429 with code `ACTIVE_PULL_LIMIT` and `limit`). Not enough credits returns 402 with `needed`, `available`, `reserved` and `total`. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours replays the original response (header `Idempotent-Replayed: true`) without creating a second list or charging again; the same key with a different body returns 400 with code `IDEMPOTENCY_KEY_REUSED`; a retry while the first request is still running returns 409 with code `IDEMPOTENCY_IN_PROGRESS`.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255,
              "pattern": "^[!-~]+$"
            },
            "example": "maricopa-absentee-2026-10-26",
            "description": "Optional. A key you choose (1-255 visible ASCII characters, no spaces) that makes retries safe. The same key and body within 24 hours replays the original response."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateListRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List created and pull started (status `processing`), or a replayed response.",
            "headers": {
              "Idempotent-Replayed": {
                "description": "Sent as \"true\" when this response replays an earlier request with the same Idempotency-Key.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                },
                "example": "true"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "get": {
        "tags": [
          "List Builder"
        ],
        "summary": "List your lists",
        "operationId": "listLists",
        "description": "Returns your lists, newest first. Lists made in the app appear too (`createdVia: \"app\"`), including combined lists made in the app (`type: \"stack\"`). Page through them with `limit` and `offset`.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            },
            "example": 50,
            "description": "Lists per page. Defaults to 50; values above 100 are treated as 100."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0,
              "maximum": 10000000
            },
            "example": 0,
            "description": "Number of lists to skip: a whole number from 0 to 10,000,000 (400 with `field: offset` otherwise)."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of lists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListsPageResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/lists/{listId}": {
      "get": {
        "tags": [
          "List Builder"
        ],
        "summary": "Get a list",
        "operationId": "getList",
        "description": "Returns one list with its status, progress and credits. While a pull runs, poll every 5-10 seconds; each poll counts toward your key's 60 requests per minute. `status` turns `completed` or `failed` only once credits are final, so `creditsCharged` is the final charge at that point. Returns 404 when the list doesn't exist and 403 when it belongs to another account.",
        "parameters": [
          {
            "name": "listId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31",
            "description": "The list ID returned by POST /lists or GET /lists."
          }
        ],
        "responses": {
          "200": {
            "description": "The list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/lists/{listId}/records": {
      "get": {
        "tags": [
          "List Builder"
        ],
        "summary": "Get list records",
        "operationId": "getListRecords",
        "description": "Returns a page of property records from a finished list. Records are ready when the list's status is `completed`, or `failed` with records kept; otherwise the call returns 400 with code `LIST_NOT_READY` (\"List is not ready yet. Current status: processing\") or `LIST_FAILED` (\"This list failed before any records were pulled.\"). Each record has a `propertyId` plus the columns you ask for, in catalog order. Values are typed: numbers as numbers; ownerOccupied, mailVacant, mtg1Heloc and activePreforeclosure as booleans; dates as YYYY-MM-DD; allLoanTypes and quickListFlags as arrays (quickListFlags holds quick-list ids); empty values as null. propType and the loan type columns use the same labels as the filter catalog (or \"Other\"); pool is true when the property has one. Other text columns, such as ownerType and foreclosureStatus, are free text with no fixed list of values. `propertyId` stays the same for a property across lists, so you can use it to dedupe. Reading records is free.",
        "parameters": [
          {
            "name": "listId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31",
            "description": "The list ID returned by POST /lists or GET /lists."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 100,
              "minimum": 1,
              "maximum": 500
            },
            "example": 100,
            "description": "Records per page. Defaults to 100; values above 500 are treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0,
              "maximum": 10000000
            },
            "example": 0,
            "description": "Number of records to skip: a whole number from 0 to 10,000,000 (400 with `field: offset` otherwise)."
          },
          {
            "name": "columns",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "propStreet,propCity,propState,propZip,ownerName,mailStreet,mailCity,mailState,mailZip",
            "description": "Comma-separated column keys from GET /lists/filters, up to 35. Repeated `columns=` parameters are also accepted. Leave it out for the 20 default columns: propStreet, propCity, propState, propZip, ownerName, owner1First, owner1Last, owner2First, owner2Last, ownerOccupied, mailStreet, mailCity, mailState, mailZip, beds, baths, sqft, yearBuilt, assessedValue, quickListFlags. Columns come back in catalog order. Available keys: apn, propStreet, propCity, propState, propZip, propZip4, county, latitude, longitude, subdivision, schoolDistrict, metroArea, censusTract, ownerName, owner1First, owner1Last, owner2First, owner2Last, owner2Name, ownerType, ownerOccupied, ownershipRights, ownershipStart, yearsOwned, mailStreet, mailCity, mailState, mailZip, mailCounty, mailVacant, propType, propCategory, landUse, beds, baths, fullBaths, sqft, grossSqft, yearBuilt, effectiveYearBuilt, stories, units, rooms, pool, garage, garageSpaces, fireplaces, airConditioning, heat, roof, exteriorWalls, construction, condition, sewer, water, lotAcres, lotSqft, zoning, legalDescription, assessedValue, marketValueTotal, marketValueLand, marketValueImprovements, assessmentYear, annualTax, taxYear, openLienBalance, openLienCount, allLoanTypes, mtg1Lender, mtg1LoanType, mtg1OriginalAmount, mtg1EstBalance, mtg1EstRate, mtg1EstPayment, mtg1Ltv, mtg1RecordingDate, mtg1TermMonths, mtg1Heloc, activePreforeclosure, foreclosureStatus, foreclosureRecordingDate, defaultDate, auctionDate, auctionTime, auctionLocation, trusteeName, trusteePhone, foreclosureLoanAmount, foreclosureLender, lienCount, lien1Type, lien1DocType, lien1RecordingDate, quickListFlags, recordUpdated."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListRecordsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/lists/{listId}/download": {
      "get": {
        "tags": [
          "List Builder"
        ],
        "summary": "Download a list as CSV",
        "operationId": "downloadList",
        "description": "Streams every record in a finished list as a CSV file named after the list. The same ready rules and `columns` parameter apply as for GET /lists/{listId}/records. The header row uses column keys (`propertyId` first, then the chosen columns), so it stays stable for parsing. Values match the records JSON: booleans as true/false and multi-value columns joined with \"; \". Cells that start with =, +, @ (or - when the value isn't a number) get a leading ' so spreadsheets don't run them as formulas. An account can run 2 downloads at a time (429 with code `DOWNLOAD_LIMIT`). Downloading is free.",
        "parameters": [
          {
            "name": "listId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31",
            "description": "The list ID returned by POST /lists or GET /lists."
          },
          {
            "name": "columns",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "propStreet,propCity,propState,propZip,ownerName,mailStreet,mailCity,mailState,mailZip",
            "description": "Comma-separated column keys from GET /lists/filters, up to 35. Repeated `columns=` parameters are also accepted. Leave it out for the 20 default columns (the same defaults as GET /lists/{listId}/records). Columns come back in catalog order. Available keys: apn, propStreet, propCity, propState, propZip, propZip4, county, latitude, longitude, subdivision, schoolDistrict, metroArea, censusTract, ownerName, owner1First, owner1Last, owner2First, owner2Last, owner2Name, ownerType, ownerOccupied, ownershipRights, ownershipStart, yearsOwned, mailStreet, mailCity, mailState, mailZip, mailCounty, mailVacant, propType, propCategory, landUse, beds, baths, fullBaths, sqft, grossSqft, yearBuilt, effectiveYearBuilt, stories, units, rooms, pool, garage, garageSpaces, fireplaces, airConditioning, heat, roof, exteriorWalls, construction, condition, sewer, water, lotAcres, lotSqft, zoning, legalDescription, assessedValue, marketValueTotal, marketValueLand, marketValueImprovements, assessmentYear, annualTax, taxYear, openLienBalance, openLienCount, allLoanTypes, mtg1Lender, mtg1LoanType, mtg1OriginalAmount, mtg1EstBalance, mtg1EstRate, mtg1EstPayment, mtg1Ltv, mtg1RecordingDate, mtg1TermMonths, mtg1Heloc, activePreforeclosure, foreclosureStatus, foreclosureRecordingDate, defaultDate, auctionDate, auctionTime, auctionLocation, trusteeName, trusteePhone, foreclosureLoanAmount, foreclosureLender, lienCount, lien1Type, lien1DocType, lien1RecordingDate, quickListFlags, recordUpdated."
          }
        ],
        "responses": {
          "200": {
            "description": "The list as a CSV file.",
            "headers": {
              "Content-Disposition": {
                "description": "attachment; filename=\"<list name>.csv\". Characters other than letters, digits, spaces, _ and - are removed from the name.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=\"Maricopa absentee high equity.csv\""
              }
            },
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/lists/{listId}/skip-trace": {
      "post": {
        "tags": [
          "List Builder"
        ],
        "summary": "Skip trace a list",
        "operationId": "skipTraceList",
        "description": "Starts a bulk skip trace of a completed list and returns a bulk `jobId`. Each record's owner names and mailing address are traced (the property address when there's no mailing address); records with no address are skipped and counted in `skippedCount`. Pricing is the normal bulk skip-trace price: each record is charged 1 credit for each requested data type actually returned (phone = 1, email = 1), so a record with no match costs nothing. `maxCredits` is reserved now and adjusted to the phones and emails actually returned when the job finishes. Track the job with GET /bulk/{jobId}/status and, once it's completed, download results with GET /bulk/{jobId}/download (JSON rows) or GET /bulk/{jobId}/download?format=csv. Results always use the standard layout: the list's columns, including `Property ID` so you can join results back to the list, then Match Found, Phone 1-6 with Line Type 1-6, Mobile 1-3, Landline 1-3 and Email 1… (see GET /bulk/{jobId}/download). The list must be `completed` with at least one record (400 with code `LIST_NOT_READY`, `LIST_FAILED` or `LIST_EMPTY`). One skip trace can be set up at a time per account (429 with code `SKIP_TRACE_IN_PROGRESS`), and when set-up is busy you may get 429 with code `SKIP_TRACE_BUSY` and a `Retry-After` header. Not enough credits returns 402 with `needed`, `available`, `reserved` and `total`. `Idempotency-Key` works the same way as on POST /lists, scoped to this list.",
        "parameters": [
          {
            "name": "listId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31",
            "description": "The list ID returned by POST /lists or GET /lists."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255,
              "pattern": "^[!-~]+$"
            },
            "example": "maricopa-absentee-skip-trace-1",
            "description": "Optional. A key you choose (1-255 visible ASCII characters, no spaces) that makes retries safe, scoped to this list. The same key and body within 24 hours replays the original response."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SkipTraceListRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Skip trace job started, or a replayed response.",
            "headers": {
              "Idempotent-Replayed": {
                "description": "Sent as \"true\" when this response replays an earlier request with the same Idempotency-Key.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                },
                "example": "true"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkipTraceListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/credits": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Check credit balance",
        "operationId": "getCredits",
        "description": "Free. Returns your credit balance; use it to check that a key works. `availableCredits` is what searches, uploads and list pulls can spend right now: `totalCredits` (subscription plus wallet credits) minus `reservedCredits`, which running bulk jobs, Digital Matching jobs, list pulls and skip traces hold until they finish. Subscription credits are spent before wallet credits, and they are set to 0 when the plan is no longer active. A paused plan gets 403 with code SUBSCRIPTION_PAUSED here too.",
        "responses": {
          "200": {
            "description": "Current credit balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/usage": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Get API usage",
        "operationId": "getUsage",
        "description": "Free. Returns request counts plus a page of your recent requests, newest first.\n\nOnly requests made with an API key are logged, one row per request once its response is sent. Requests refused before that (401s, RATE_LIMITED 429s and paused-plan 403s) aren't logged. `creditsUsed` is the charge a search reported; every other request logs 0, including uploads, list creates and list skip traces, because their charge is settled when the job finishes. `stats.totalCreditsUsed` adds those final job charges.\n\nPaging: new requests, your /usage calls included, are added at the top while you page, so rows can shift between pages; dedupe by `id`. There is no total, and `hasMore` is true whenever a page is full, so stop when a page has fewer rows than `limit`.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            },
            "example": 50,
            "description": "Rows per page. Defaults to 50; values above 100 are treated as 100. Must be a whole number of 1 or more (400 with `field: limit` otherwise)."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0,
              "maximum": 10000000
            },
            "example": 0,
            "description": "Rows to skip: a whole number from 0 to 10,000,000 (400 with `field: offset` otherwise)."
          }
        ],
        "responses": {
          "200": {
            "description": "Usage statistics and recent activity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sk_live_...",
        "description": "Send your key in the Authorization header exactly as `Authorization: Bearer sk_live_...`: the word Bearer with a capital B, one space, then the whole key. Keys are sk_live_ followed by 64 hexadecimal characters. Any other form, such as a lower-case \"bearer\", returns 401 \"Invalid or missing API key\".\n\nCreate keys in the app at Settings → API Access. A key is shown once, when you create it, and can't be shown again. Keys have no scopes and don't expire. An account can have several active keys, so to rotate one: create a new key, deploy it, then revoke the old key in Settings; a revoked key is refused from its next request. If API access is turned off for the account, calls return 401 \"API access is not enabled for this account\"; contact support.\n\nKeep keys on your server. The API sends no CORS headers, so it can't be called from a web page. Each key is rate limited to 60 requests per minute (see the API description)."
      }
    },
    "schemas": {
      "DeepSearchRequest": {
        "type": "object",
        "required": [
          "lastName"
        ],
        "description": "The person to look up. Only lastName is validated as required, but a search that matches too many people returns 400 with code INSUFFICIENT_INPUT: add a first name and a ZIP code, or a city and state. Fields not listed here are ignored, not refused.",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "First name. Optional, but most searches need it to narrow the match to one person.",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "minLength": 1,
            "description": "Last name. Required. Deep Search looks up people, so a company, LLC or trust name usually finds no match; send an owner's personal name.",
            "example": "Smith"
          },
          "address": {
            "type": "string",
            "description": "Street address.",
            "example": "123 Main St"
          },
          "city": {
            "type": "string",
            "description": "City.",
            "example": "Austin"
          },
          "state": {
            "type": "string",
            "description": "Two-letter state code.",
            "example": "TX"
          },
          "zip": {
            "type": "string",
            "description": "ZIP code.",
            "example": "78701"
          }
        },
        "example": {
          "firstName": "John",
          "lastName": "Smith",
          "address": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701"
        }
      },
      "StandardSearchRequest": {
        "type": "object",
        "required": [
          "lastName",
          "dataTypes"
        ],
        "description": "The person to look up. lastName and dataTypes are the only fields validated as required, but the search needs a name and a complete address (street plus ZIP, or city and state); otherwise it returns 400 with code INSUFFICIENT_INPUT. Fields not listed here are ignored, not refused.",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "First name.",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "minLength": 1,
            "description": "Last name. Required.",
            "example": "Smith"
          },
          "address": {
            "type": "string",
            "description": "Street address. Send it with zip, or with city and state.",
            "example": "123 Main St"
          },
          "city": {
            "type": "string",
            "description": "City.",
            "example": "Austin"
          },
          "state": {
            "type": "string",
            "description": "Two-letter state code.",
            "example": "TX"
          },
          "zip": {
            "type": "string",
            "description": "ZIP code.",
            "example": "78701"
          },
          "dataTypes": {
            "type": "array",
            "minItems": 1,
            "description": "Which contact data to return, and the price on a match: [\"phone\"] = 1 credit, [\"email\"] = 1 credit, [\"phone\",\"email\"] = 2 credits, charged even when a requested type comes back empty. List each type once: the API doesn't remove repeats, so [\"phone\",\"phone\"] is charged 2 credits.",
            "items": {
              "type": "string",
              "enum": [
                "phone",
                "email"
              ]
            },
            "example": [
              "phone",
              "email"
            ]
          }
        },
        "example": {
          "firstName": "John",
          "lastName": "Smith",
          "address": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701",
          "dataTypes": [
            "phone",
            "email"
          ]
        }
      },
      "Phone": {
        "type": "object",
        "description": "One phone number.",
        "required": [
          "number"
        ],
        "properties": {
          "number": {
            "type": "string",
            "description": "The phone number. Deep Search removes dashes, parentheses and spaces. Standard Search returns the number as the source formats it, so normalize to 10 digits before you compare or dial.",
            "example": "5125551234"
          },
          "lineType": {
            "type": "string",
            "description": "The line type as the source reports it, for example Mobile or Landline. Free text with no fixed list of values, so compare case-insensitively: mobile, cell and wireless mean a mobile line; landline and land line mean a landline. Omitted when unknown.",
            "example": "Mobile"
          },
          "disconnected": {
            "type": "boolean",
            "description": "Deep Search only, where it is always sent: true when the source flags the number as disconnected. Standard Search phones don't have this field.",
            "example": false
          }
        },
        "example": {
          "number": "5125551234",
          "lineType": "Mobile",
          "disconnected": false
        }
      },
      "Email": {
        "type": "string",
        "description": "One email address, as a plain string (not an object). Deep Search returns it in lower case.",
        "example": "john.smith@example.com"
      },
      "Address": {
        "type": "object",
        "description": "A postal address.",
        "required": [
          "address",
          "city",
          "state",
          "zip"
        ],
        "properties": {
          "address": {
            "type": "string",
            "description": "Street address.",
            "example": "123 Main St"
          },
          "city": {
            "type": "string",
            "description": "City. Empty string when unknown.",
            "example": "Austin"
          },
          "state": {
            "type": "string",
            "description": "State. Empty string when unknown.",
            "example": "TX"
          },
          "zip": {
            "type": "string",
            "description": "ZIP code. Empty string when unknown. Deep Search puts ZIP+4 in this field when it has it (78701-1234); Standard Search returns the 4-digit add-on separately in zip4.",
            "example": "78701"
          },
          "zip4": {
            "type": "string",
            "description": "Standard Search only: the ZIP+4 add-on code, when known. Omitted otherwise.",
            "example": "1234"
          }
        },
        "example": {
          "address": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701"
        }
      },
      "Subject": {
        "type": "object",
        "description": "Present only when matchFound is true: the person the search matched. Optional fields are left out when the source has no value; they are never null.",
        "required": [
          "deceased",
          "phones",
          "emails",
          "addresses",
          "bankruptcy"
        ],
        "properties": {
          "firstName": {
            "type": "string",
            "description": "First name. Omitted when unknown.",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "Last name. Omitted when unknown.",
            "example": "Smith"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Other names on record, as full names. Omitted (not an empty array) when there are none.",
            "example": [
              "John A Smith"
            ]
          },
          "age": {
            "type": "integer",
            "description": "Age in years. Omitted when unknown.",
            "example": 45
          },
          "dob": {
            "type": "string",
            "description": "Date of birth as the source reports it. Omitted when unknown."
          },
          "deceased": {
            "type": "boolean",
            "description": "true when a death record was found. false means no record was found, not that the person is confirmed alive.",
            "example": false
          },
          "phones": {
            "type": "array",
            "description": "Phone numbers. Can be empty.",
            "items": {
              "$ref": "#/components/schemas/Phone"
            }
          },
          "emails": {
            "type": "array",
            "description": "Email addresses as plain strings, in lower case. Can be empty.",
            "items": {
              "$ref": "#/components/schemas/Email"
            }
          },
          "addresses": {
            "type": "array",
            "description": "Known addresses. Can be empty.",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "bankruptcy": {
            "type": "boolean",
            "description": "true when a bankruptcy record was found. false means no record was found.",
            "example": false
          }
        },
        "example": {
          "firstName": "John",
          "lastName": "Smith",
          "aliases": [
            "John A Smith"
          ],
          "age": 45,
          "deceased": false,
          "phones": [
            {
              "number": "5125551234",
              "lineType": "Mobile",
              "disconnected": false
            },
            {
              "number": "5125559876",
              "lineType": "Landline",
              "disconnected": false
            }
          ],
          "emails": [
            "john.smith@example.com"
          ],
          "addresses": [
            {
              "address": "123 Main St",
              "city": "Austin",
              "state": "TX",
              "zip": "78701-1234"
            }
          ],
          "bankruptcy": false
        }
      },
      "RelatedPerson": {
        "type": "object",
        "description": "A relative or associate of the subject. At least one of firstName and lastName is present. Related people come back with phone numbers only: emails and addresses are always empty arrays today.",
        "required": [
          "deceased",
          "relationship",
          "phones",
          "emails",
          "addresses",
          "bankruptcy"
        ],
        "properties": {
          "firstName": {
            "type": "string",
            "description": "First name. Omitted when unknown.",
            "example": "Jane"
          },
          "lastName": {
            "type": "string",
            "description": "Last name. Omitted when unknown.",
            "example": "Smith"
          },
          "age": {
            "type": "integer",
            "description": "Age in years. Omitted when unknown.",
            "example": 43
          },
          "deceased": {
            "type": "boolean",
            "description": "true when a death record was found. false means no record was found.",
            "example": false
          },
          "relationship": {
            "type": "string",
            "description": "How this person relates to the subject: Spouse, Parent, Child, Sibling, Other Relative, Roommate, Neighbor, Business Associate, Relative, Associate or Related. New values may be added later.",
            "example": "Spouse"
          },
          "phones": {
            "type": "array",
            "description": "Phone numbers. Can be empty.",
            "items": {
              "$ref": "#/components/schemas/Phone"
            }
          },
          "emails": {
            "type": "array",
            "description": "Always empty today.",
            "items": {
              "$ref": "#/components/schemas/Email"
            },
            "example": []
          },
          "addresses": {
            "type": "array",
            "description": "Always empty today.",
            "items": {
              "$ref": "#/components/schemas/Address"
            },
            "example": []
          },
          "bankruptcy": {
            "type": "boolean",
            "description": "true when a bankruptcy record was found. false means no record was found.",
            "example": false
          }
        },
        "example": {
          "firstName": "Jane",
          "lastName": "Smith",
          "age": 43,
          "deceased": false,
          "relationship": "Spouse",
          "phones": [
            {
              "number": "5125554321",
              "lineType": "Mobile",
              "disconnected": false
            }
          ],
          "emails": [],
          "addresses": [],
          "bankruptcy": false
        }
      },
      "DeepSearchResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/DeepSearchResult"
          }
        },
        "example": {
          "success": true,
          "data": {
            "matchFound": true,
            "subject": {
              "firstName": "John",
              "lastName": "Smith",
              "aliases": [
                "John A Smith"
              ],
              "age": 45,
              "deceased": false,
              "phones": [
                {
                  "number": "5125551234",
                  "lineType": "Mobile",
                  "disconnected": false
                },
                {
                  "number": "5125559876",
                  "lineType": "Landline",
                  "disconnected": false
                }
              ],
              "emails": [
                "john.smith@example.com"
              ],
              "addresses": [
                {
                  "address": "123 Main St",
                  "city": "Austin",
                  "state": "TX",
                  "zip": "78701-1234"
                }
              ],
              "bankruptcy": false
            },
            "relatedPeople": [
              {
                "firstName": "Jane",
                "lastName": "Smith",
                "age": 43,
                "deceased": false,
                "relationship": "Spouse",
                "phones": [
                  {
                    "number": "5125554321",
                    "lineType": "Mobile",
                    "disconnected": false
                  }
                ],
                "emails": [],
                "addresses": [],
                "bankruptcy": false
              }
            ],
            "creditsCharged": 10
          }
        }
      },
      "DeepSearchResult": {
        "type": "object",
        "required": [
          "matchFound",
          "creditsCharged"
        ],
        "properties": {
          "matchFound": {
            "type": "boolean",
            "description": "true when a person record matched. A match can still have no phones or emails; see creditsCharged.",
            "example": true
          },
          "subject": {
            "$ref": "#/components/schemas/Subject"
          },
          "relatedPeople": {
            "type": "array",
            "description": "Present only when matchFound is true: relatives and associates of the subject. Can be empty.",
            "items": {
              "$ref": "#/components/schemas/RelatedPerson"
            }
          },
          "creditsCharged": {
            "type": "integer",
            "description": "10 when the result includes at least one phone, email or related person; otherwise 0, including matches that return only an address or identity. Total your spend from this field, not from matchFound.",
            "example": 10
          }
        }
      },
      "StandardSearchResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/StandardSearchResult"
          }
        },
        "example": {
          "success": true,
          "data": {
            "matchFound": true,
            "phones": [
              {
                "number": "5125551234",
                "lineType": "Mobile"
              },
              {
                "number": "5125559876",
                "lineType": "Landline"
              }
            ],
            "emails": [
              "john.smith@example.com"
            ],
            "name": {
              "first": "John",
              "last": "Smith"
            },
            "addresses": [
              {
                "address": "123 Main St",
                "city": "Austin",
                "state": "TX",
                "zip": "78701",
                "zip4": "1234"
              }
            ],
            "matchType": "Individual",
            "creditsCharged": 2
          }
        }
      },
      "StandardSearchResult": {
        "type": "object",
        "required": [
          "matchFound",
          "creditsCharged"
        ],
        "properties": {
          "matchFound": {
            "type": "boolean",
            "description": "true when a person or household matched.",
            "example": true
          },
          "phones": {
            "type": "array",
            "description": "Present only when \"phone\" was requested and a match was found. Can be empty. Ordered with up to 2 mobile numbers first, then 1 landline, then the rest.",
            "items": {
              "$ref": "#/components/schemas/Phone"
            }
          },
          "emails": {
            "type": "array",
            "description": "Present only when \"email\" was requested and a match was found. Plain strings. Can be empty.",
            "items": {
              "$ref": "#/components/schemas/Email"
            }
          },
          "name": {
            "$ref": "#/components/schemas/PersonName"
          },
          "addresses": {
            "type": "array",
            "description": "Present only when matchFound is true: the matched address. Zero or one entry today.",
            "items": {
              "$ref": "#/components/schemas/Address"
            },
            "example": [
              {
                "address": "123 Main St",
                "city": "Austin",
                "state": "TX",
                "zip": "78701",
                "zip4": "1234"
              }
            ]
          },
          "matchType": {
            "type": "string",
            "description": "Present only when matchFound is true: Individual or Household. Individual means the contact data matched the named person. Household means it matched at the household level, so a phone or email may belong to another person at the same address.",
            "example": "Individual"
          },
          "creditsCharged": {
            "type": "integer",
            "description": "On a match, the number of data types requested (1 credit each), even when a type came back empty; a repeated type counts again. 0 when there is no match.",
            "example": 2
          }
        }
      },
      "PersonName": {
        "type": "object",
        "description": "Present only when matchFound is true: the matched name. A part is omitted when the source has none.",
        "properties": {
          "first": {
            "type": "string",
            "description": "First name.",
            "example": "John"
          },
          "last": {
            "type": "string",
            "description": "Last name.",
            "example": "Smith"
          }
        },
        "example": {
          "first": "John",
          "last": "Smith"
        }
      },
      "BulkUploadResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/BulkUploadResult"
          }
        }
      },
      "BulkUploadResult": {
        "type": "object",
        "required": [
          "jobId",
          "lookupId",
          "recordCount",
          "dataTypes",
          "creditsPerMatch",
          "status",
          "message"
        ],
        "properties": {
          "jobId": {
            "type": "string",
            "description": "Use with GET /bulk/{jobId}/status and GET /bulk/{jobId}/download.",
            "example": "abc123-def456"
          },
          "lookupId": {
            "type": "string",
            "description": "The job's entry in History in the app. No API endpoint takes it.",
            "example": "xyz789"
          },
          "recordCount": {
            "type": "integer",
            "description": "Rows that will be searched: the data rows minus skippedCount.",
            "example": 497
          },
          "dataTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "phone",
                "email"
              ]
            },
            "description": "The data types you sent, as sent (repeats are kept).",
            "example": [
              "phone",
              "email"
            ]
          },
          "creditsPerMatch": {
            "type": "integer",
            "description": "The number of data types you sent, repeats included. recordCount × creditsPerMatch credits are reserved; the final charge is 1 credit for each requested data type actually returned per row.",
            "example": 2
          },
          "status": {
            "type": "string",
            "description": "Always \"processing\" in this response. The first status checks can still show \"uploading\" or \"queued\".",
            "example": "processing"
          },
          "skippedCount": {
            "type": "integer",
            "description": "Present only when rows were skipped: rows that met no input combination. They aren't searched, charged or included in the results.",
            "example": 3
          },
          "skippedReason": {
            "type": "string",
            "description": "Present only when rows were skipped: why, with the accepted combinations.",
            "example": "3 row(s) were skipped because they don't include enough info to be searchable (they won't be charged). Each row needs at least one of these combinations to be searchable: First + Last Name + ZIP; First + Last Name + City + State; Street Address + City + State + ZIP. A single full-name column counts as First + Last Name, except for company names (LLC, Inc., etc.), which need the full street address, city, state, and ZIP."
          },
          "message": {
            "type": "string",
            "description": "A readable summary. Don't parse it.",
            "example": "Processing 497 records (3 skipped — not enough info to be searchable; skipped rows are never charged). Use GET /api/v1/bulk/abc123-def456/status to check progress."
          }
        }
      },
      "BulkStatusResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/BulkJobStatus"
          }
        }
      },
      "BulkJobStatus": {
        "type": "object",
        "required": [
          "jobId",
          "status",
          "progress",
          "estimatedSecondsRemaining",
          "numRecords",
          "numMatches",
          "errorMessage"
        ],
        "properties": {
          "jobId": {
            "type": "string",
            "example": "abc123-def456"
          },
          "status": {
            "type": "string",
            "description": "uploading, queued or processing while the job runs, then completed or failed. Treat any value you don't recognize as still running. Rarely, a failed job moves back to processing, so check once more before you upload the same file again.",
            "example": "processing",
            "enum": [
              "uploading",
              "queued",
              "processing",
              "completed",
              "failed"
            ]
          },
          "progress": {
            "type": "integer",
            "description": "Percent complete (0-100).",
            "example": 65
          },
          "estimatedSecondsRemaining": {
            "type": "integer",
            "nullable": true,
            "description": "Rough time left in seconds, or null when there is no estimate.",
            "example": 120
          },
          "numRecords": {
            "type": "integer",
            "description": "Rows in the job.",
            "example": 497
          },
          "numMatches": {
            "type": "integer",
            "nullable": true,
            "description": "Rows matched so far; final once status is completed.",
            "example": 312
          },
          "errorMessage": {
            "type": "string",
            "description": "An empty string (\"\") unless status is failed; then a short reason.",
            "example": ""
          }
        }
      },
      "AudienceUploadResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/AudienceUploadResult"
          }
        }
      },
      "AudienceUploadResult": {
        "type": "object",
        "required": [
          "jobId",
          "lookupId",
          "recordCount",
          "platforms",
          "creditsPerMatch",
          "status",
          "message"
        ],
        "properties": {
          "jobId": {
            "type": "string",
            "description": "Use with GET /audience/{jobId}/status and GET /audience/{jobId}/download.",
            "example": "abc123-def456"
          },
          "lookupId": {
            "type": "string",
            "description": "The job's entry in History in the app. No API endpoint takes it.",
            "example": "xyz789"
          },
          "recordCount": {
            "type": "integer",
            "description": "Every data row in the file. Rows aren't checked one by one at upload.",
            "example": 500
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "facebook",
                "google",
                "linkedin",
                "tiktok",
                "generic"
              ]
            },
            "description": "The selected platforms, repeats removed.",
            "example": [
              "facebook",
              "google"
            ]
          },
          "creditsPerMatch": {
            "type": "integer",
            "description": "Credits charged for each matched contact, every selected platform included. recordCount × creditsPerMatch credits are reserved now. Read the price here rather than hard-coding it.",
            "example": 2
          },
          "status": {
            "type": "string",
            "description": "Always \"processing\" in this response.",
            "example": "processing"
          },
          "message": {
            "type": "string",
            "description": "A readable summary. Don't parse it.",
            "example": "Processing 500 records. Use GET /api/v1/audience/abc123-def456/status to check progress."
          }
        }
      },
      "AudienceStatusResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/AudienceJobStatus"
          }
        }
      },
      "AudienceJobStatus": {
        "type": "object",
        "required": [
          "jobId",
          "status",
          "progress",
          "numRecords",
          "numMatches",
          "creditsCharged",
          "platforms",
          "platformCounts",
          "errorMessage"
        ],
        "properties": {
          "jobId": {
            "type": "string",
            "example": "abc123-def456"
          },
          "status": {
            "type": "string",
            "description": "uploading, queued or processing while the job runs, then completed or failed. Treat any value you don't recognize as still running. Rarely, a failed job moves back to processing, so check once more before you upload the same file again.",
            "example": "processing",
            "enum": [
              "uploading",
              "queued",
              "processing",
              "completed",
              "failed"
            ]
          },
          "progress": {
            "type": "integer",
            "description": "Percent complete (0-100).",
            "example": 65
          },
          "numRecords": {
            "type": "integer",
            "description": "Rows in the job.",
            "example": 500
          },
          "numMatches": {
            "type": "integer",
            "nullable": true,
            "description": "Matched contacts (each charged creditsPerMatch). Final once status is completed.",
            "example": 312
          },
          "creditsCharged": {
            "type": "integer",
            "nullable": true,
            "description": "Credits charged for the job. Final once status is completed.",
            "example": 624
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The job's platforms.",
            "example": [
              "facebook",
              "google"
            ]
          },
          "platformCounts": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Matched contacts per platform. null until the job completes.",
            "example": {
              "facebook": 298,
              "google": 305
            }
          },
          "errorMessage": {
            "type": "string",
            "description": "An empty string (\"\") unless status is failed; then a short reason.",
            "example": ""
          }
        }
      },
      "BulkDownloadResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/BulkDownloadResult"
          }
        }
      },
      "BulkDownloadResult": {
        "type": "object",
        "required": [
          "jobId",
          "numRecords",
          "numMatches",
          "creditsCharged",
          "results"
        ],
        "properties": {
          "jobId": {
            "type": "string",
            "example": "abc123-def456"
          },
          "numRecords": {
            "type": "integer",
            "description": "Rows in the job.",
            "example": 497
          },
          "numMatches": {
            "type": "integer",
            "nullable": true,
            "description": "Rows matched.",
            "example": 312
          },
          "creditsCharged": {
            "type": "integer",
            "nullable": true,
            "description": "Final credits charged for the job.",
            "example": 401
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Standard layout only: the column names in order (your columns, then Match Found, Phone 1, Line Type 1 … Landline 3, Email 1 …).",
            "example": [
              "Owner Name",
              "Property ID",
              "Match Found",
              "Phone 1",
              "Line Type 1"
            ]
          },
          "results": {
            "oneOf": [
              {
                "type": "array",
                "description": "Standard layout (list skip traces, or layout=standard): one object per record, keyed by the names in `columns`. Every value is a string.",
                "items": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "string",
                "description": "Original shape for bulk upload jobs without layout=standard: the results file as one CSV text string."
              }
            ],
            "description": "Per-record results. An array of row objects in the standard layout; see the endpoint description for when the original shape is returned instead.",
            "example": [
              {
                "Owner Name": "Jane Sample",
                "Property ID": "prop_3f9a1c2e7b4d8e6f0a1b2c3d",
                "Match Found": "Yes",
                "Phone 1": "6025550123",
                "Line Type 1": "Mobile",
                "Mobile 1": "6025550123",
                "Email 1": "jane@example.com"
              }
            ]
          }
        }
      },
      "CreditsResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/CreditBalance"
          }
        }
      },
      "CreditBalance": {
        "type": "object",
        "required": [
          "subscriptionCredits",
          "walletCredits",
          "reservedCredits",
          "totalCredits",
          "availableCredits",
          "subscriptionStatus"
        ],
        "properties": {
          "subscriptionCredits": {
            "type": "integer",
            "description": "Credits from your plan. Spent first; set to 0 when the plan is no longer active.",
            "example": 3000
          },
          "walletCredits": {
            "type": "integer",
            "description": "Wallet credits, outside the plan. Spent after subscription credits.",
            "example": 1500
          },
          "reservedCredits": {
            "type": "integer",
            "description": "Credits held by running bulk jobs, Digital Matching jobs, list pulls and skip traces. They are charged or released when each one finishes.",
            "example": 500
          },
          "totalCredits": {
            "type": "integer",
            "description": "subscriptionCredits + walletCredits.",
            "example": 4500
          },
          "availableCredits": {
            "type": "integer",
            "description": "totalCredits − reservedCredits: what you can spend right now. Check this one.",
            "example": 4000
          },
          "subscriptionStatus": {
            "type": "string",
            "description": "The plan's status, for example active, trialing, past_due, canceled or none. Searches, uploads and List Builder previews, pulls and skip traces need active or trialing (403 with code SUBSCRIPTION_REQUIRED otherwise). A paused plan gets 403 with code SUBSCRIPTION_PAUSED on every endpoint, this one included.",
            "example": "active"
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/UsageReport"
          }
        }
      },
      "UsageReport": {
        "type": "object",
        "required": [
          "stats",
          "recentActivity",
          "pagination"
        ],
        "properties": {
          "stats": {
            "$ref": "#/components/schemas/UsageStats"
          },
          "recentActivity": {
            "type": "array",
            "description": "A page of logged requests, newest first.",
            "items": {
              "$ref": "#/components/schemas/UsageLogEntry"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/UsagePagination"
          }
        }
      },
      "UsageStats": {
        "type": "object",
        "required": [
          "totalRequests",
          "totalCreditsUsed",
          "requestsToday",
          "requestsThisMonth"
        ],
        "properties": {
          "totalRequests": {
            "type": "integer",
            "description": "Every logged request on the account.",
            "example": 1250
          },
          "totalCreditsUsed": {
            "type": "integer",
            "description": "Credits charged to logged requests, plus the final charges of finished jobs and list pulls started with an API key.",
            "example": 8400
          },
          "requestsToday": {
            "type": "integer",
            "description": "Requests since midnight, server time (which may not be your time zone).",
            "example": 45
          },
          "requestsThisMonth": {
            "type": "integer",
            "description": "Requests since the first of the month, server time.",
            "example": 890
          }
        }
      },
      "UsageLogEntry": {
        "type": "object",
        "required": [
          "id",
          "endpoint",
          "method",
          "statusCode",
          "creditsUsed",
          "timestamp"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The log row's ID. Use it to dedupe rows across pages.",
            "example": "4b8e2f6a-1c3d-4e5f-8a9b-0c1d2e3f4a5b"
          },
          "endpoint": {
            "type": "string",
            "description": "The path that was called, including any query string.",
            "example": "/api/v1/deep-search"
          },
          "method": {
            "type": "string",
            "example": "POST"
          },
          "statusCode": {
            "type": "integer",
            "description": "The HTTP status the request returned.",
            "example": 200
          },
          "creditsUsed": {
            "type": "integer",
            "description": "The charge a search reported. 0 for every other request, including uploads, list creates and list skip traces, whose charge is settled when the job finishes.",
            "example": 10
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When the response was sent (ISO 8601, UTC).",
            "example": "2026-10-26T15:04:05.123Z"
          }
        }
      },
      "UsagePagination": {
        "type": "object",
        "required": [
          "limit",
          "offset",
          "hasMore"
        ],
        "properties": {
          "limit": {
            "type": "integer",
            "example": 50
          },
          "offset": {
            "type": "integer",
            "example": 0
          },
          "hasMore": {
            "type": "boolean",
            "description": "true when this page is full (as many rows as limit). It can be true on the last page, so stop when a page has fewer rows than limit.",
            "example": false
          }
        }
      },
      "DateRange": {
        "type": "object",
        "description": "A fixed custom date window. Leave out `to` for an open end: up to today for the look-back keys and filings.within, no end date for auctionNextDays.",
        "required": [
          "from"
        ],
        "additionalProperties": false,
        "properties": {
          "from": {
            "type": "string",
            "format": "date",
            "description": "Start date, YYYY-MM-DD.",
            "example": "2026-07-01"
          },
          "to": {
            "type": "string",
            "format": "date",
            "description": "Optional end date, YYYY-MM-DD, on or after `from`.",
            "example": "2026-09-30"
          }
        },
        "example": {
          "from": "2026-07-01",
          "to": "2026-09-30"
        }
      },
      "NumberRange": {
        "type": "object",
        "description": "A numeric range. Send `min`, `max` or both. Each must be a non-negative number, and `min` must be less than or equal to `max`.",
        "additionalProperties": false,
        "properties": {
          "min": {
            "type": "number",
            "minimum": 0,
            "description": "Lowest value to include.",
            "example": 2
          },
          "max": {
            "type": "number",
            "minimum": 0,
            "description": "Highest value to include.",
            "example": 4
          }
        },
        "example": {
          "min": 2,
          "max": 4
        }
      },
      "SavedListLocation": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "state",
          "kind"
        ],
        "description": "Where a saved list searches. Lists made through the API have kind city, county or zip with `values`, as sent. Lists made in the app can also have kind address (`values`: 1-50 street addresses written \"STREET, CITY, ST 12345\"), radius (a circle: `center`, `miles` and `label`) or polygon (a drawn shape: `points` and `label`). `label`, `centerSource` and `shape` are display names only. New kinds may be added; treat one you don't recognize as an area you can read but not send.",
        "properties": {
          "state": {
            "type": "string",
            "description": "Two-letter US state code, or DC.",
            "example": "AZ"
          },
          "kind": {
            "type": "string",
            "enum": [
              "city",
              "county",
              "zip",
              "address",
              "radius",
              "polygon"
            ],
            "example": "radius"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "city, county, zip and address lists: what the list searches.",
            "example": [
              "Maricopa"
            ]
          },
          "center": {
            "type": "object",
            "description": "radius lists: the circle's center.",
            "properties": {
              "lat": {
                "type": "number",
                "example": 33.47457
              },
              "lng": {
                "type": "number",
                "example": -112.07384
              }
            }
          },
          "miles": {
            "type": "number",
            "minimum": 0.1,
            "maximum": 50,
            "description": "radius lists: the circle's radius in miles.",
            "example": 1
          },
          "points": {
            "type": "array",
            "minItems": 3,
            "maxItems": 500,
            "description": "polygon lists: the shape's corners in order, as an open ring (the first point isn't repeated at the end).",
            "items": {
              "type": "object",
              "properties": {
                "lat": {
                  "type": "number"
                },
                "lng": {
                  "type": "number"
                }
              }
            }
          },
          "label": {
            "type": "string",
            "maxLength": 120,
            "description": "radius and polygon lists: the area's name in the app.",
            "example": "Within 1 mi of 2400 N Central Ave"
          },
          "centerSource": {
            "type": "string",
            "enum": [
              "address",
              "map"
            ],
            "description": "radius lists: whether the center came from an address or a map click."
          },
          "shape": {
            "type": "string",
            "enum": [
              "rectangle",
              "custom"
            ],
            "description": "polygon lists: how the shape was drawn."
          }
        },
        "example": {
          "state": "AZ",
          "kind": "radius",
          "center": {
            "lat": 33.47457,
            "lng": -112.07384
          },
          "miles": 1,
          "label": "Within 1 mi of 2400 N Central Ave"
        }
      },
      "ListFilters": {
        "type": "object",
        "description": "Which properties to pull: the same filters the List Builder page uses. Only `location` is required; leave a filter out to include every value. Unknown keys are refused with 400. GET /lists/filters returns every allowed value.",
        "required": [
          "location"
        ],
        "additionalProperties": false,
        "properties": {
          "location": {
            "type": "object",
            "description": "The area to search: one state and one location type per list. Values of that type combine, so a property in any of them matches.",
            "required": [
              "state",
              "kind",
              "values"
            ],
            "additionalProperties": false,
            "properties": {
              "state": {
                "type": "string",
                "minLength": 2,
                "maxLength": 2,
                "description": "Two-letter US state code, or DC. Case doesn't matter; it's saved upper-case.",
                "example": "AZ"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "city",
                  "county",
                  "zip"
                ],
                "description": "The type of every value in `values`.",
                "example": "county"
              },
              "values": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "description": "1-50 cities, counties or ZIP codes in that state, matching `kind`. ZIP codes must be 5 digits.",
                "example": [
                  "Maricopa"
                ]
              }
            },
            "example": {
              "state": "AZ",
              "kind": "county",
              "values": [
                "Maricopa"
              ]
            }
          },
          "quicklists": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "string",
              "enum": [
                "preforeclosure",
                "absentee-owner",
                "out-of-state-absentee-owner",
                "high-equity",
                "low-equity",
                "free-and-clear",
                "vacant",
                "vacant-lot",
                "tax-default",
                "tired-landlord",
                "corporate-owned",
                "trust-owned",
                "inherited",
                "cash-buyer",
                "senior-owner",
                "expired-listing",
                "for-sale-by-owner",
                "on-market",
                "off-market",
                "recently-sold",
                "involuntary-lien",
                "notice-of-default",
                "owner-occupied"
              ]
            },
            "description": "Up to 10 quick lists (distress and equity signals). GET /lists/filters has each one's label and description. Allowed values: preforeclosure (Pre-Foreclosure): Owners who received a foreclosure notice but haven't lost the home yet — often motivated to sell fast. | absentee-owner (Absentee Owner): Owners whose mailing address differs from the property — they don't live there. | out-of-state-absentee-owner (Out-of-State Owner): Absentee owners whose mailing address is in a different state entirely. | high-equity (High Equity): Owners with more than 20% equity in the property — room to negotiate on price. | low-equity (Low Equity): Owners with 20% or less equity — they still owe the lender most of the property's value. | free-and-clear (Free & Clear): Properties with no mortgage at all — the owner owns it outright. | vacant (Vacant): Flagged vacant by USPS — mail isn't being collected at the property. | vacant-lot (Vacant Lot): Empty land parcels with no building on them. | tax-default (Tax Default): Properties in active tax default whose first default was more than 3 years ago. | tired-landlord (Tired Landlord): Single-family rentals owned 10+ years and built 30+ years ago — landlords who may be ready to move on. | corporate-owned (Corporate Owned): Properties owned by a company or LLC rather than a person. | trust-owned (Trust Owned): Properties held in a family or living trust. | inherited (Inherited): Properties recently transferred within a family — heirs often prefer to sell. | cash-buyer (Cash Buyer): Owners who recently bought property with cash or a hard-money loan — often active investors. | senior-owner (Senior Owner): Owners flagged as seniors: 25+ years in the home, a senior tax exemption, or an open reverse mortgage. | expired-listing (Expired Listing): Properties that were listed for sale but didn't sell before the listing expired. | for-sale-by-owner (For Sale By Owner): Properties the owner is selling themselves, without a listing agent. | on-market (On Market): Properties currently listed for sale on the market. | off-market (Off Market): Properties NOT currently listed for sale — everything except active listings. | recently-sold (Recently Sold): Properties that sold within the last 12 months. | involuntary-lien (Involuntary Lien): Properties with a lien filed against them (judgment, HOA, mechanic's, etc.). | notice-of-default (Notice of Default): Owners formally notified they're in default on their mortgage. | owner-occupied (Owner Occupied): Properties where the owner lives in the home.",
            "example": [
              "absentee-owner",
              "high-equity"
            ]
          },
          "quicklistMatch": {
            "type": "string",
            "enum": [
              "any",
              "all"
            ],
            "default": "any",
            "description": "How quick lists combine: \"any\" (the default) includes homes on any picked list; \"all\" includes only homes on every picked list.",
            "example": "all"
          },
          "ownerType": {
            "type": "string",
            "enum": [
              "individual",
              "company",
              "trust"
            ],
            "description": "Who owns the property. Leave it out for any owner.",
            "example": "individual"
          },
          "propertyTypes": {
            "type": "array",
            "maxItems": 6,
            "items": {
              "type": "string",
              "enum": [
                "single-family",
                "multi-family-2-4",
                "apartments-5plus",
                "condo-townhouse",
                "mobile-manufactured",
                "commercial"
              ]
            },
            "description": "Property types to include. Leave it out for every type.",
            "example": [
              "single-family"
            ]
          },
          "zoning": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "description": "Zoning code prefix, for example \"R1\". Zoning codes vary by county.",
            "example": "R1"
          },
          "hasPool": {
            "type": "boolean",
            "description": "Only true is accepted: true keeps homes with a pool. Leave it out to include homes with or without a pool (false is refused).",
            "example": true
          },
          "loanTypes": {
            "type": "array",
            "maxItems": 8,
            "items": {
              "type": "string",
              "enum": [
                "conventional",
                "fha",
                "va",
                "usda",
                "reverse",
                "arm",
                "seller-financed",
                "heloc"
              ]
            },
            "description": "First-mortgage loan types to include.",
            "example": [
              "fha",
              "va"
            ]
          },
          "lienTypes": {
            "type": "array",
            "maxItems": 6,
            "items": {
              "type": "string",
              "enum": [
                "federal-tax",
                "state-tax",
                "mechanics",
                "assessment",
                "support",
                "economic"
              ]
            },
            "description": "Involuntary lien types to include.",
            "example": [
              "federal-tax",
              "state-tax"
            ]
          },
          "distressTiming": {
            "type": "object",
            "description": "Timing windows for distress and event quick lists. Each value is a preset day count or a custom DateRange. A timing key only works with its quick list picked: auctionNextDays and foreclosureFiledDays need preforeclosure or notice-of-default, lienRecordedDays needs involuntary-lien, expiredDays needs expired-listing, and soldDays needs recently-sold.",
            "additionalProperties": false,
            "properties": {
              "auctionNextDays": {
                "oneOf": [
                  {
                    "type": "integer",
                    "enum": [
                      7,
                      14,
                      30,
                      60,
                      90
                    ]
                  },
                  {
                    "$ref": "#/components/schemas/DateRange"
                  }
                ],
                "description": "Auction scheduled in the next 7, 14, 30, 60 or 90 days, or a custom date range. Needs preforeclosure or notice-of-default.",
                "example": 30
              },
              "foreclosureFiledDays": {
                "oneOf": [
                  {
                    "type": "integer",
                    "enum": [
                      30,
                      60,
                      90,
                      180,
                      365
                    ]
                  },
                  {
                    "$ref": "#/components/schemas/DateRange"
                  }
                ],
                "description": "Foreclosure filed in the last 30, 60, 90, 180 or 365 days, or a custom date range. Needs preforeclosure or notice-of-default.",
                "example": 90
              },
              "lienRecordedDays": {
                "oneOf": [
                  {
                    "type": "integer",
                    "enum": [
                      30,
                      90,
                      180,
                      365
                    ]
                  },
                  {
                    "$ref": "#/components/schemas/DateRange"
                  }
                ],
                "description": "Lien recorded in the last 30, 90, 180 or 365 days, or a custom date range. Needs involuntary-lien.",
                "example": 180
              },
              "expiredDays": {
                "oneOf": [
                  {
                    "type": "integer",
                    "enum": [
                      7,
                      14,
                      30,
                      60,
                      90
                    ]
                  },
                  {
                    "$ref": "#/components/schemas/DateRange"
                  }
                ],
                "description": "Listing expired in the last 7, 14, 30, 60 or 90 days, or a custom date range. Needs expired-listing.",
                "example": 30
              },
              "soldDays": {
                "oneOf": [
                  {
                    "type": "integer",
                    "enum": [
                      30,
                      60,
                      90,
                      180,
                      365
                    ]
                  },
                  {
                    "$ref": "#/components/schemas/DateRange"
                  }
                ],
                "description": "Sold in the last 30, 60, 90, 180 or 365 days, or a custom date range. Needs recently-sold.",
                "example": 90
              }
            },
            "example": {
              "foreclosureFiledDays": 90,
              "auctionNextDays": 30
            }
          },
          "filings": {
            "type": "object",
            "description": "Probate & Death Records: homes with a probate filing or death record recorded within the window. Not available in AK, CT, DC, DE, MA, MD, ME, ND, NH, NJ, RI or VT. Can't be combined with the recently-sold quick list, distressTiming.soldDays, distressTiming.lienRecordedDays or lienTypes.",
            "required": [
              "kind",
              "within"
            ],
            "additionalProperties": false,
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "probate",
                  "death",
                  "both"
                ],
                "description": "Probate filings, death records, or both.",
                "example": "both"
              },
              "within": {
                "oneOf": [
                  {
                    "type": "integer",
                    "enum": [
                      30,
                      60,
                      90,
                      180,
                      365
                    ]
                  },
                  {
                    "$ref": "#/components/schemas/DateRange"
                  }
                ],
                "description": "Recorded in the last 30, 60, 90, 180 or 365 days, or a custom date range that starts within the last 12 months.",
                "example": 180
              }
            },
            "example": {
              "kind": "both",
              "within": 180
            }
          },
          "ranges": {
            "type": "object",
            "description": "Numeric ranges. Each key takes a NumberRange with `min`, `max` or both.",
            "additionalProperties": false,
            "properties": {
              "beds": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Bedrooms.",
                "example": {
                  "min": 3
                }
              },
              "baths": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Bathrooms.",
                "example": {
                  "min": 2
                }
              },
              "sqft": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Square feet of living area.",
                "example": {
                  "min": 1200,
                  "max": 2500
                }
              },
              "yearBuilt": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Year built.",
                "example": {
                  "min": 1960
                }
              },
              "lotSizeAcres": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Lot size in acres.",
                "example": {
                  "max": 0.5
                }
              },
              "yearsOwned": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Years the current owner has held the property.",
                "example": {
                  "min": 10
                }
              },
              "assessedValue": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "County assessed value in US dollars.",
                "example": {
                  "max": 300000
                }
              },
              "unitCount": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Units in the building.",
                "example": {
                  "min": 2,
                  "max": 4
                }
              },
              "storyCount": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Stories.",
                "example": {
                  "max": 2
                }
              },
              "openLienBalance": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Estimated balance of open mortgages in US dollars.",
                "example": {
                  "max": 100000
                }
              },
              "openLienCount": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NumberRange"
                  }
                ],
                "description": "Number of open mortgages.",
                "example": {
                  "max": 1
                }
              }
            },
            "example": {
              "yearBuilt": {
                "min": 1960
              }
            }
          }
        },
        "example": {
          "location": {
            "state": "AZ",
            "kind": "county",
            "values": [
              "Maricopa"
            ]
          },
          "quicklists": [
            "absentee-owner",
            "high-equity"
          ],
          "quicklistMatch": "all",
          "propertyTypes": [
            "single-family"
          ],
          "ranges": {
            "yearBuilt": {
              "min": 1960
            }
          }
        }
      },
      "ListResource": {
        "type": "object",
        "properties": {
          "listId": {
            "type": "string",
            "format": "uuid",
            "description": "The list's ID.",
            "example": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31"
          },
          "name": {
            "type": "string",
            "description": "The list's name.",
            "example": "Maricopa absentee high equity"
          },
          "type": {
            "type": "string",
            "description": "\"search\" for lists built from filters; \"stack\" for combined lists made in the app. New values may be added later.",
            "example": "search"
          },
          "status": {
            "type": "string",
            "description": "\"processing\", \"completed\" or \"failed\". \"completed\" and \"failed\" are set only once credits are final. New values may be added later; treat an unknown value as \"processing\".",
            "example": "processing"
          },
          "progress": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Percent complete (0-100).",
            "example": 0
          },
          "recordCount": {
            "type": "integer",
            "description": "Records pulled so far.",
            "example": 0
          },
          "maxRecords": {
            "type": "integer",
            "description": "The most records this list will pull.",
            "example": 500
          },
          "creditsReserved": {
            "type": "integer",
            "description": "Credits held for this list right now: the full reservation while it is processing, then 0 once it finishes (the charge moves to creditsCharged and the unused part is released).",
            "example": 500
          },
          "creditsCharged": {
            "type": "integer",
            "description": "Credits charged for records pulled. Final once status is \"completed\" or \"failed\".",
            "example": 0
          },
          "filters": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "The filters the list was built with, as saved: the same fields as the ListFilters request object (state upper-case, empty filter lists filled in). Fields may be added later. null for stacked lists. A list made in the app can also have a location the API doesn't take yet (street addresses or a map area; see `location`) and `ranges.estimatedValue` (the estimated home value, in dollars, as {min, max}), which the API doesn't take yet either.",
            "properties": {
              "location": {
                "$ref": "#/components/schemas/SavedListLocation"
              }
            },
            "example": {
              "location": {
                "state": "AZ",
                "kind": "county",
                "values": [
                  "Maricopa"
                ]
              },
              "quicklists": [
                "absentee-owner",
                "high-equity"
              ],
              "quicklistMatch": "all",
              "propertyTypes": [
                "single-family"
              ],
              "loanTypes": [],
              "lienTypes": [],
              "ranges": {
                "yearBuilt": {
                  "min": 1960
                }
              }
            }
          },
          "errorMessage": {
            "type": "string",
            "nullable": true,
            "description": "null unless status is \"failed\". Then it is always: \"The pull stopped before it finished. Records pulled before it stopped are kept and charged; the rest of the reserved credits were released.\"",
            "example": null
          },
          "createdVia": {
            "type": "string",
            "description": "\"api\" for lists made with an API key, \"app\" for lists made in the app. New values may be added later.",
            "example": "api"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the list was created (ISO 8601).",
            "example": "2026-10-26T15:04:05.000Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the list last changed (ISO 8601).",
            "example": "2026-10-26T15:04:05.000Z"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the list finished, completed or failed (ISO 8601). null while status is processing.",
            "example": null
          }
        }
      },
      "ListResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/ListResource"
          }
        }
      },
      "ListsPageResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/ListsPage"
          }
        }
      },
      "ListsPage": {
        "type": "object",
        "properties": {
          "lists": {
            "type": "array",
            "description": "Your lists, newest first.",
            "items": {
              "$ref": "#/components/schemas/ListResource"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/ListsPagination"
          }
        }
      },
      "ListsPagination": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "example": 50
          },
          "offset": {
            "type": "integer",
            "example": 0
          },
          "total": {
            "type": "integer",
            "description": "Lists on the account.",
            "example": 12
          },
          "hasMore": {
            "type": "boolean",
            "example": false
          }
        }
      },
      "PreviewRequest": {
        "type": "object",
        "required": [
          "filters"
        ],
        "additionalProperties": false,
        "properties": {
          "filters": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ListFilters"
              }
            ],
            "description": "The filters to count. Use the same filters you plan to send to POST /lists.",
            "example": {
              "location": {
                "state": "AZ",
                "kind": "county",
                "values": [
                  "Maricopa"
                ]
              },
              "quicklists": [
                "absentee-owner",
                "high-equity"
              ],
              "quicklistMatch": "all",
              "propertyTypes": [
                "single-family"
              ],
              "ranges": {
                "yearBuilt": {
                  "min": 1960
                }
              }
            }
          },
          "maxRecords": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000,
            "description": "Optional cap to estimate with (1-100,000). Without it, the estimate uses the match count, up to 100,000.",
            "example": 500
          }
        }
      },
      "PreviewResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/PreviewResult"
          }
        }
      },
      "PreviewResult": {
        "type": "object",
        "properties": {
          "matchCount": {
            "type": "integer",
            "description": "Properties that match the filters.",
            "example": 1842
          },
          "creditsPerRecord": {
            "type": "integer",
            "description": "Credits per record pulled.",
            "example": 1
          },
          "maxRecordsLimit": {
            "type": "integer",
            "description": "The most records one list can pull.",
            "example": 100000
          },
          "maxRecords": {
            "type": "integer",
            "description": "The cap used for this estimate: your maxRecords, or the match count up to 100,000.",
            "example": 500
          },
          "recordsToPull": {
            "type": "integer",
            "description": "Records a pull would return: the smaller of matchCount and maxRecords.",
            "example": 500
          },
          "estimatedCredits": {
            "type": "integer",
            "description": "Credits a pull of recordsToPull would charge.",
            "example": 500
          },
          "creditsToReserve": {
            "type": "integer",
            "description": "Credits POST /lists would reserve for this maxRecords. Unused credits are released.",
            "example": 500
          }
        }
      },
      "CreateListRequest": {
        "type": "object",
        "required": [
          "name",
          "maxRecords",
          "filters"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "A name for the list (1-120 characters).",
            "example": "Maricopa absentee high equity"
          },
          "maxRecords": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000,
            "description": "The most records to pull (1-100,000). This many credits are reserved up front; set it to the preview's recordsToPull to hold only what you need.",
            "example": 500
          },
          "filters": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ListFilters"
              }
            ],
            "description": "Which properties to pull.",
            "example": {
              "location": {
                "state": "AZ",
                "kind": "county",
                "values": [
                  "Maricopa"
                ]
              },
              "quicklists": [
                "absentee-owner",
                "high-equity"
              ],
              "quicklistMatch": "all",
              "propertyTypes": [
                "single-family"
              ],
              "ranges": {
                "yearBuilt": {
                  "min": 1960
                }
              }
            }
          }
        }
      },
      "ListRecordsResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/ListRecordsPage"
          }
        }
      },
      "ListRecordsPage": {
        "type": "object",
        "properties": {
          "listId": {
            "type": "string",
            "format": "uuid",
            "example": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31"
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The column keys in each record, in catalog order. propertyId is always included too.",
            "example": [
              "propStreet",
              "propCity",
              "propState",
              "propZip",
              "ownerName",
              "owner1First",
              "owner1Last",
              "owner2First",
              "owner2Last",
              "ownerOccupied",
              "mailStreet",
              "mailCity",
              "mailState",
              "mailZip",
              "beds",
              "baths",
              "sqft",
              "yearBuilt",
              "assessedValue",
              "quickListFlags"
            ]
          },
          "records": {
            "type": "array",
            "description": "One object per property: propertyId plus each requested column. A column's type is listed in GET /lists/filters; empty values are null.",
            "items": {
              "$ref": "#/components/schemas/ListRecord"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/ListRecordsPagination"
          }
        }
      },
      "ListRecord": {
        "type": "object",
        "required": [
          "propertyId"
        ],
        "properties": {
          "propertyId": {
            "type": "string",
            "pattern": "^prop_[0-9a-f]{24}$",
            "description": "Stays the same for a property across lists. Use it to dedupe.",
            "example": "prop_3f9a1c2e7b4d8e6f0a1b2c3d"
          }
        },
        "additionalProperties": {
          "oneOf": [
            {
              "type": "string",
              "nullable": true
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          ]
        },
        "example": {
          "propertyId": "prop_3f9a1c2e7b4d8e6f0a1b2c3d",
          "propStreet": "1234 W Example St",
          "propCity": "Phoenix",
          "propState": "AZ",
          "propZip": "85015",
          "ownerName": "Jane Sample",
          "owner1First": "Jane",
          "owner1Last": "Sample",
          "owner2First": null,
          "owner2Last": null,
          "ownerOccupied": false,
          "mailStreet": "PO Box 100",
          "mailCity": "Tempe",
          "mailState": "AZ",
          "mailZip": "85281",
          "beds": 3,
          "baths": 2,
          "sqft": 1450,
          "yearBuilt": 1978,
          "assessedValue": 28400,
          "quickListFlags": [
            "absentee-owner",
            "high-equity"
          ]
        }
      },
      "ListRecordsPagination": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "example": 0
          },
          "total": {
            "type": "integer",
            "description": "Records in the list.",
            "example": 500
          },
          "hasMore": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "ListFiltersResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/FiltersCatalog"
          }
        }
      },
      "FiltersCatalog": {
        "type": "object",
        "properties": {
          "location": {
            "type": "object",
            "example": {
              "types": [
                "city",
                "county",
                "zip"
              ],
              "maxValues": 50,
              "states": [
                "AL",
                "AK",
                "AZ",
                "AR",
                "CA",
                "CO",
                "CT",
                "DE",
                "FL",
                "GA",
                "HI",
                "ID",
                "IL",
                "IN",
                "IA",
                "KS",
                "KY",
                "LA",
                "ME",
                "MD",
                "MA",
                "MI",
                "MN",
                "MS",
                "MO",
                "MT",
                "NE",
                "NV",
                "NH",
                "NJ",
                "NM",
                "NY",
                "NC",
                "ND",
                "OH",
                "OK",
                "OR",
                "PA",
                "RI",
                "SC",
                "SD",
                "TN",
                "TX",
                "UT",
                "VT",
                "VA",
                "WA",
                "WV",
                "WI",
                "WY",
                "DC"
              ]
            },
            "properties": {
              "types": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Accepted values for filters.location.kind.",
                "example": [
                  "city",
                  "county",
                  "zip"
                ]
              },
              "maxValues": {
                "type": "integer",
                "description": "The most values filters.location.values can hold.",
                "example": 50
              },
              "states": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Accepted state codes: the 50 states and DC.",
                "example": [
                  "AL",
                  "AK",
                  "AZ",
                  "AR",
                  "CA",
                  "CO",
                  "CT",
                  "DE",
                  "FL",
                  "GA",
                  "HI",
                  "ID",
                  "IL",
                  "IN",
                  "IA",
                  "KS",
                  "KY",
                  "LA",
                  "ME",
                  "MD",
                  "MA",
                  "MI",
                  "MN",
                  "MS",
                  "MO",
                  "MT",
                  "NE",
                  "NV",
                  "NH",
                  "NJ",
                  "NM",
                  "NY",
                  "NC",
                  "ND",
                  "OH",
                  "OK",
                  "OR",
                  "PA",
                  "RI",
                  "SC",
                  "SD",
                  "TN",
                  "TX",
                  "UT",
                  "VT",
                  "VA",
                  "WA",
                  "WV",
                  "WI",
                  "WY",
                  "DC"
                ]
              }
            }
          },
          "quicklists": {
            "type": "array",
            "description": "Every quick list, with the timing keys it owns.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Use in filters.quicklists.",
                  "example": "involuntary-lien"
                },
                "label": {
                  "type": "string",
                  "example": "Involuntary Lien"
                },
                "description": {
                  "type": "string",
                  "example": "Properties with a lien filed against them (judgment, HOA, mechanic's, etc.)."
                },
                "timing": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "distressTiming keys that need this quick list picked.",
                  "example": [
                    "lienRecordedDays"
                  ]
                }
              }
            },
            "example": [
              {
                "id": "absentee-owner",
                "label": "Absentee Owner",
                "description": "Owners whose mailing address differs from the property — they don't live there.",
                "timing": []
              },
              {
                "id": "involuntary-lien",
                "label": "Involuntary Lien",
                "description": "Properties with a lien filed against them (judgment, HOA, mechanic's, etc.).",
                "timing": [
                  "lienRecordedDays"
                ]
              }
            ]
          },
          "quicklistMatch": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Accepted values for filters.quicklistMatch.",
            "example": [
              "any",
              "all"
            ]
          },
          "maxQuicklists": {
            "type": "integer",
            "description": "The most quick lists one list can use.",
            "example": 10
          },
          "ownerTypes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Use in filters.ownerType.",
                  "example": "individual"
                },
                "label": {
                  "type": "string",
                  "example": "Individual"
                }
              }
            },
            "example": [
              {
                "id": "individual",
                "label": "Individual"
              },
              {
                "id": "company",
                "label": "Company"
              },
              {
                "id": "trust",
                "label": "Trust"
              }
            ]
          },
          "propertyTypes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Use in filters.propertyTypes.",
                  "example": "single-family"
                },
                "label": {
                  "type": "string",
                  "example": "Single Family"
                }
              }
            },
            "example": [
              {
                "id": "single-family",
                "label": "Single Family"
              },
              {
                "id": "multi-family-2-4",
                "label": "Multi-Family (2–4)"
              },
              {
                "id": "apartments-5plus",
                "label": "Apartments (5+)"
              },
              {
                "id": "condo-townhouse",
                "label": "Condo / Townhouse"
              },
              {
                "id": "mobile-manufactured",
                "label": "Mobile / Manufactured"
              },
              {
                "id": "commercial",
                "label": "Commercial"
              }
            ]
          },
          "loanTypes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Use in filters.loanTypes.",
                  "example": "fha"
                },
                "label": {
                  "type": "string",
                  "example": "FHA"
                }
              }
            },
            "example": [
              {
                "id": "conventional",
                "label": "Conventional"
              },
              {
                "id": "fha",
                "label": "FHA"
              },
              {
                "id": "va",
                "label": "VA"
              }
            ]
          },
          "lienTypes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Use in filters.lienTypes.",
                  "example": "federal-tax"
                },
                "label": {
                  "type": "string",
                  "example": "Federal Tax Lien"
                }
              }
            },
            "example": [
              {
                "id": "federal-tax",
                "label": "Federal Tax Lien"
              },
              {
                "id": "state-tax",
                "label": "State Tax Lien"
              }
            ]
          },
          "distressTiming": {
            "type": "object",
            "description": "One entry per timing key: its preset day counts, whether it looks back (past) or ahead (next), whether custom dates are accepted, and the quick lists it needs.",
            "example": {
              "auctionNextDays": {
                "presetDays": [
                  7,
                  14,
                  30,
                  60,
                  90
                ],
                "direction": "next",
                "customDates": true,
                "requiresQuickList": [
                  "preforeclosure",
                  "notice-of-default"
                ]
              },
              "foreclosureFiledDays": {
                "presetDays": [
                  30,
                  60,
                  90,
                  180,
                  365
                ],
                "direction": "past",
                "customDates": true,
                "requiresQuickList": [
                  "preforeclosure",
                  "notice-of-default"
                ]
              },
              "lienRecordedDays": {
                "presetDays": [
                  30,
                  90,
                  180,
                  365
                ],
                "direction": "past",
                "customDates": true,
                "requiresQuickList": [
                  "involuntary-lien"
                ]
              },
              "expiredDays": {
                "presetDays": [
                  7,
                  14,
                  30,
                  60,
                  90
                ],
                "direction": "past",
                "customDates": true,
                "requiresQuickList": [
                  "expired-listing"
                ]
              },
              "soldDays": {
                "presetDays": [
                  30,
                  60,
                  90,
                  180,
                  365
                ],
                "direction": "past",
                "customDates": true,
                "requiresQuickList": [
                  "recently-sold"
                ]
              }
            },
            "properties": {
              "auctionNextDays": {
                "type": "object",
                "properties": {
                  "presetDays": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "example": [
                      7,
                      14,
                      30,
                      60,
                      90
                    ]
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "past",
                      "next"
                    ],
                    "example": "next"
                  },
                  "customDates": {
                    "type": "boolean",
                    "example": true
                  },
                  "requiresQuickList": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "preforeclosure",
                      "notice-of-default"
                    ]
                  }
                }
              },
              "foreclosureFiledDays": {
                "type": "object",
                "properties": {
                  "presetDays": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "example": [
                      30,
                      60,
                      90,
                      180,
                      365
                    ]
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "past",
                      "next"
                    ],
                    "example": "past"
                  },
                  "customDates": {
                    "type": "boolean",
                    "example": true
                  },
                  "requiresQuickList": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "preforeclosure",
                      "notice-of-default"
                    ]
                  }
                }
              },
              "lienRecordedDays": {
                "type": "object",
                "properties": {
                  "presetDays": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "example": [
                      30,
                      90,
                      180,
                      365
                    ]
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "past",
                      "next"
                    ],
                    "example": "past"
                  },
                  "customDates": {
                    "type": "boolean",
                    "example": true
                  },
                  "requiresQuickList": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "involuntary-lien"
                    ]
                  }
                }
              },
              "expiredDays": {
                "type": "object",
                "properties": {
                  "presetDays": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "example": [
                      7,
                      14,
                      30,
                      60,
                      90
                    ]
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "past",
                      "next"
                    ],
                    "example": "past"
                  },
                  "customDates": {
                    "type": "boolean",
                    "example": true
                  },
                  "requiresQuickList": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "expired-listing"
                    ]
                  }
                }
              },
              "soldDays": {
                "type": "object",
                "properties": {
                  "presetDays": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "example": [
                      30,
                      60,
                      90,
                      180,
                      365
                    ]
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "past",
                      "next"
                    ],
                    "example": "past"
                  },
                  "customDates": {
                    "type": "boolean",
                    "example": true
                  },
                  "requiresQuickList": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "recently-sold"
                    ]
                  }
                }
              }
            }
          },
          "filings": {
            "type": "object",
            "description": "Options for filters.filings (Probate & Death Records).",
            "example": {
              "kinds": [
                {
                  "id": "probate",
                  "label": "Probate filings"
                },
                {
                  "id": "death",
                  "label": "Death records"
                },
                {
                  "id": "both",
                  "label": "Both"
                }
              ],
              "presetDays": [
                30,
                60,
                90,
                180,
                365
              ],
              "maxLookbackDays": 365,
              "unavailableStates": [
                "AK",
                "CT",
                "DC",
                "DE",
                "MA",
                "MD",
                "ME",
                "ND",
                "NH",
                "NJ",
                "RI",
                "VT"
              ],
              "cannotCombineWith": [
                "recently-sold",
                "distressTiming.soldDays",
                "distressTiming.lienRecordedDays",
                "lienTypes"
              ]
            },
            "properties": {
              "kinds": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Use in filters.filings.kind.",
                      "example": "probate"
                    },
                    "label": {
                      "type": "string",
                      "example": "Probate filings"
                    }
                  }
                },
                "example": [
                  {
                    "id": "probate",
                    "label": "Probate filings"
                  },
                  {
                    "id": "death",
                    "label": "Death records"
                  },
                  {
                    "id": "both",
                    "label": "Both"
                  }
                ]
              },
              "presetDays": {
                "type": "array",
                "items": {
                  "type": "integer"
                },
                "example": [
                  30,
                  60,
                  90,
                  180,
                  365
                ]
              },
              "maxLookbackDays": {
                "type": "integer",
                "description": "How far back a custom date range may start.",
                "example": 365
              },
              "unavailableStates": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "States where Probate & Death Records can't be used.",
                "example": [
                  "AK",
                  "CT",
                  "DC",
                  "DE",
                  "MA",
                  "MD",
                  "ME",
                  "ND",
                  "NH",
                  "NJ",
                  "RI",
                  "VT"
                ]
              },
              "cannotCombineWith": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Quick lists and filter paths that can't be used together with filings.",
                "example": [
                  "recently-sold",
                  "distressTiming.soldDays",
                  "distressTiming.lienRecordedDays",
                  "lienTypes"
                ]
              }
            }
          },
          "ranges": {
            "type": "array",
            "description": "Every key accepted in filters.ranges, with its unit.",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "example": "yearBuilt"
                },
                "unit": {
                  "type": "string",
                  "example": "year"
                }
              }
            },
            "example": [
              {
                "field": "beds",
                "unit": "bedrooms"
              },
              {
                "field": "yearBuilt",
                "unit": "year"
              },
              {
                "field": "assessedValue",
                "unit": "US dollars (county assessed value)"
              }
            ]
          },
          "maxRecordsLimit": {
            "type": "integer",
            "description": "The most records one list can pull.",
            "example": 100000
          },
          "creditsPerRecord": {
            "type": "integer",
            "description": "Credits per record pulled.",
            "example": 1
          },
          "columns": {
            "type": "array",
            "description": "Every record column you can request, in catalog order.",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Use in the columns parameter.",
                  "example": "propStreet"
                },
                "label": {
                  "type": "string",
                  "example": "Property Address"
                },
                "category": {
                  "type": "string",
                  "example": "Location"
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "string",
                    "number",
                    "boolean",
                    "date",
                    "list"
                  ],
                  "description": "The JSON type of the value. \"date\" is a YYYY-MM-DD string; \"list\" is an array of strings.",
                  "example": "string"
                },
                "default": {
                  "type": "boolean",
                  "description": "Whether the column is returned when you don't send columns.",
                  "example": true
                }
              }
            },
            "example": [
              {
                "key": "propStreet",
                "label": "Property Address",
                "category": "Location",
                "type": "string",
                "default": true
              },
              {
                "key": "ownerOccupied",
                "label": "Owner Occupied",
                "category": "Owner",
                "type": "boolean",
                "default": true
              },
              {
                "key": "auctionDate",
                "label": "Auction Date",
                "category": "Foreclosure",
                "type": "date",
                "default": false
              }
            ]
          },
          "maxColumns": {
            "type": "integer",
            "description": "The most columns one request can ask for.",
            "example": 35
          }
        }
      },
      "SkipTraceListRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "dataTypes": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "enum": [
                "phone",
                "email"
              ]
            },
            "default": [
              "phone"
            ],
            "description": "Which contact data to append: [\"phone\"] (the default), [\"email\"] or [\"phone\",\"email\"]. Each data type costs 1 credit per match.",
            "example": [
              "phone",
              "email"
            ]
          }
        }
      },
      "SkipTraceListResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/SkipTraceListResult"
          }
        }
      },
      "SkipTraceListResult": {
        "type": "object",
        "properties": {
          "jobId": {
            "type": "string",
            "description": "Use with GET /bulk/{jobId}/status and GET /bulk/{jobId}/download.",
            "example": "abc123-def456"
          },
          "listId": {
            "type": "string",
            "format": "uuid",
            "example": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31"
          },
          "recordCount": {
            "type": "integer",
            "description": "Records sent for skip tracing.",
            "example": 497
          },
          "skippedCount": {
            "type": "integer",
            "description": "Records left out because they have no mailing or property address.",
            "example": 3
          },
          "dataTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "phone",
                "email"
              ]
            },
            "example": [
              "phone",
              "email"
            ]
          },
          "creditsPerMatch": {
            "type": "integer",
            "description": "The most one record can cost: the number of data types requested. Each record is charged 1 credit for each requested data type actually returned, so a phone-only result costs 1.",
            "example": 2
          },
          "maxCredits": {
            "type": "integer",
            "description": "recordCount × creditsPerMatch, reserved now and adjusted to the phones and emails actually returned when the job finishes.",
            "example": 994
          },
          "status": {
            "type": "string",
            "example": "processing"
          },
          "message": {
            "type": "string",
            "example": "Skip trace started. Track it with GET /bulk/{jobId}/status and download results with GET /bulk/{jobId}/download?format=csv once it completes."
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Every error body. Only success and error are always present; the other fields appear on the errors listed under each one. Branch on the HTTP status first, because many errors have no code.",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "description": "What went wrong, in plain English. Always present. Don't parse it; it can change.",
            "example": "Insufficient credits"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable reason. Many errors have no code: every 401, search 402s, most upload 400s, and the Digital Matching and other-account 403s. Codes sent today:\n- 400: INVALID_JSON (the body isn't a valid JSON object), INSUFFICIENT_INPUT (a search can't run with the details sent; credits refunded), INVALID_UPLOAD (the multipart body is broken, or the file was sent in a field other than file; a request that isn't multipart, or has no file part, returns 400 \"CSV file is required...\" with no code), LIST_NOT_READY, LIST_FAILED, LIST_EMPTY, UNSUPPORTED_CONTENT_TYPE, INVALID_IDEMPOTENCY_KEY, IDEMPOTENCY_KEY_REUSED.\n- 403: SUBSCRIPTION_REQUIRED, SUBSCRIPTION_PAUSED, LIST_BUILDER_DISABLED.\n- 409: IDEMPOTENCY_IN_PROGRESS.\n- 413: BODY_TOO_LARGE, FILE_TOO_LARGE.\n- 429: RATE_LIMITED (the per-key limit of 60 requests per minute), PREVIEW_MINUTE_LIMIT, PREVIEW_DAILY_LIMIT, ACTIVE_PULL_LIMIT, DOWNLOAD_LIMIT, SKIP_TRACE_IN_PROGRESS, SKIP_TRACE_BUSY.\n- 503: PREVIEW_UNAVAILABLE.\nNew codes may be added later; handle a code you don't recognize by its HTTP status.",
            "example": "INSUFFICIENT_INPUT"
          },
          "field": {
            "type": "string",
            "description": "Sent with some 400s: the request field that failed, for example limit, offset, layout or filters.location.state. Deep Search and Standard Search validation errors don't include it.",
            "example": "filters.location.state"
          },
          "message": {
            "type": "string",
            "description": "Sent by some errors as a copy of error, for older clients. Read error instead."
          },
          "needed": {
            "type": "integer",
            "description": "402 from bulk upload, Digital Matching upload, POST /lists and list skip trace: the credits the request needs. Search 402s don't include it.",
            "example": 1000
          },
          "available": {
            "type": "integer",
            "description": "With needed: credits available now.",
            "example": 400
          },
          "reserved": {
            "type": "integer",
            "description": "With needed: credits held by running jobs.",
            "example": 100
          },
          "total": {
            "type": "integer",
            "description": "With needed: your total balance.",
            "example": 500
          },
          "resumeAt": {
            "type": "integer",
            "nullable": true,
            "description": "With SUBSCRIPTION_PAUSED, when known: when the paused plan resumes on its own, as a Unix timestamp in seconds, or null when no resume date is set.",
            "example": 1767225600
          },
          "retryAfter": {
            "type": "integer",
            "minimum": 1,
            "description": "With RATE_LIMITED: whole seconds until the key's window resets, the same value as the Retry-After header. Wait that long before the next request.",
            "example": 42
          },
          "limit": {
            "type": "integer",
            "description": "With RATE_LIMITED (requests per key per minute, 60), PREVIEW_MINUTE_LIMIT, PREVIEW_DAILY_LIMIT, ACTIVE_PULL_LIMIT and DOWNLOAD_LIMIT: the limit you hit.",
            "example": 250
          },
          "resetsAt": {
            "type": "string",
            "format": "date-time",
            "description": "With RATE_LIMITED: when the key's 60-second window resets. With PREVIEW_DAILY_LIMIT: when the daily count resets (the next UTC midnight).",
            "example": "2026-10-27T00:00:00.000Z"
          },
          "maxBatchSize": {
            "type": "integer",
            "description": "400 when an upload, or a list sent to skip trace, has more rows than one job allows: the most rows allowed.",
            "example": 250000
          },
          "recordCount": {
            "type": "integer",
            "description": "With maxBatchSize on an upload: the data rows in your file.",
            "example": 300000
          },
          "invalidCount": {
            "type": "integer",
            "description": "400 from bulk upload when no row can be searched: the number of data rows.",
            "example": 120
          }
        },
        "example": {
          "success": false,
          "error": "Insufficient credits"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request can't be processed as sent; fix it before retrying (LIST_NOT_READY is the exception: retry once the list completes). Codes: INVALID_JSON, INSUFFICIENT_INPUT (Deep Search or Standard Search can't run with the details sent; credits refunded), INVALID_UPLOAD, and the List Builder codes LIST_NOT_READY, LIST_FAILED, LIST_EMPTY, UNSUPPORTED_CONTENT_TYPE, INVALID_IDEMPOTENCY_KEY and IDEMPOTENCY_KEY_REUSED. Many 400s have no code: search validation errors name only the first problem, with no field (for example \"Required\" when lastName is missing or the body wasn't sent as application/json), and most upload 400s explain the problem in error only. Uploads add maxBatchSize and recordCount when a file has too many rows, and invalidCount when no row can be searched.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "insufficientInput": {
                "summary": "Standard Search without a complete address",
                "value": {
                  "success": false,
                  "error": "The search needs a name and a complete address (street plus ZIP, or city and state). Credits have been refunded.",
                  "code": "INSUFFICIENT_INPUT"
                }
              },
              "tooManyRows": {
                "summary": "Bulk upload over the row cap",
                "value": {
                  "success": false,
                  "error": "Batch size exceeds limit. Maximum 250000 records per upload.",
                  "maxBatchSize": 250000,
                  "recordCount": 300000
                }
              },
              "invalidField": {
                "summary": "A bad query parameter",
                "value": {
                  "success": false,
                  "error": "offset must be a whole number from 0 to 10000000.",
                  "field": "offset"
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The API key is missing, malformed, revoked, or can't be used. No code is sent; error is one of: \"Invalid or missing API key\" (no Authorization header, or not exactly \"Bearer sk_live_...\"), \"Invalid or inactive API key\" (wrong or revoked key), \"API access is not enabled for this account\" (API access is turned off for the account; contact support) or \"Account is suspended\". Don't retry until the key or account is fixed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "success": false,
              "error": "Invalid or inactive API key"
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "Not enough available credits (total minus reserved). Deep Search and Standard Search return just \"Insufficient credits\"; Deep Search needs 10 available credits to start, even when the result ends up free. Bulk upload, Digital Matching upload, POST /lists and list skip trace add needed, available, reserved and total. Add credits, or wait for running jobs to release reserved credits, then retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "search": {
                "summary": "Deep Search or Standard Search",
                "value": {
                  "success": false,
                  "error": "Insufficient credits"
                }
              },
              "upload": {
                "summary": "Bulk upload",
                "value": {
                  "success": false,
                  "error": "Insufficient credits. You need up to 1000 credits but only have 400 available (100 reserved for pending jobs, 500 total).",
                  "needed": 1000,
                  "available": 400,
                  "reserved": 100,
                  "total": 500
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The account can't use this endpoint or resource. code SUBSCRIPTION_REQUIRED: no active or trialing plan (searches, uploads, and List Builder previews, pulls and skip traces). code SUBSCRIPTION_PAUSED: the plan is paused, on every endpoint; resumeAt, when sent, is when it resumes on its own. code LIST_BUILDER_DISABLED: List Builder isn't turned on for the account. No code: \"Digital Matching access is not enabled for this account\", or \"Access denied\" when the job or list belongs to another account. Don't retry until the account changes.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "subscriptionRequired": {
                "summary": "No active plan",
                "value": {
                  "success": false,
                  "error": "Active subscription required",
                  "message": "Active subscription required",
                  "code": "SUBSCRIPTION_REQUIRED"
                }
              },
              "subscriptionPaused": {
                "summary": "Paused plan",
                "value": {
                  "success": false,
                  "error": "Your plan is paused. Resume your subscription to continue.",
                  "code": "SUBSCRIPTION_PAUSED",
                  "resumeAt": 1767225600
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "The job, list or path doesn't exist (\"Job not found\", \"List not found\" or \"Not found\"), the job was deleted from History in the app, or a job ID was sent to the wrong endpoint:a non-Digital Matching job to /audience/{jobId}/..., or a Digital Matching job to /bulk/{jobId}/download with layout=standard. Unknown paths and wrong HTTP methods also return 404, not 405.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "success": false,
              "error": "Job not found"
            }
          }
        }
      },
      "Conflict": {
        "description": "A request with this Idempotency-Key is still in progress (code IDEMPOTENCY_IN_PROGRESS). Retry with the same key once the first request finishes.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The request is too large. code BODY_TOO_LARGE: a JSON body over 1 MB. code FILE_TOO_LARGE: an uploaded file over 100 MB. Send less data per request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "success": false,
              "error": "The file is too large (100 MB maximum).",
              "code": "FILE_TOO_LARGE"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests. The per-key limit is 60 requests in a fixed 60-second window that starts with the key's first request, and every request made with the key counts, including errors, status polls and downloads. That 429 has code RATE_LIMITED, a Retry-After header, and in the body `retryAfter` (the same seconds), `limit` (60) and `resetsAt` (when the window resets): wait Retry-After seconds, then retry. Counts are kept per server instance, so always honor Retry-After rather than X-RateLimit-Remaining. List Builder limits carry their own codes: PREVIEW_MINUTE_LIMIT (limit, Retry-After: 60), PREVIEW_DAILY_LIMIT (limit, resetsAt and Retry-After), ACTIVE_PULL_LIMIT (limit), DOWNLOAD_LIMIT (limit), SKIP_TRACE_IN_PROGRESS and SKIP_TRACE_BUSY (Retry-After: 10). When Retry-After is sent, wait that many seconds; when it isn't, wait a few seconds and back off exponentially. The X-RateLimit-* headers on any 429 describe the per-key limit only.",
        "headers": {
          "Retry-After": {
            "description": "Whole seconds to wait before retrying. Sent only with codes RATE_LIMITED (seconds until the key's 60-second window resets, 1 to 60, the same as `retryAfter` in the body), PREVIEW_MINUTE_LIMIT (60), PREVIEW_DAILY_LIMIT (seconds until the next UTC midnight) and SKIP_TRACE_BUSY (10).",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 42
          },
          "X-RateLimit-Limit": {
            "description": "Requests allowed per API key in each 60-second window: 60.",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 60
          },
          "X-RateLimit-Remaining": {
            "description": "Requests this key has left in the current window (0 on the 429). Counts are kept per server instance, so treat this as a guide and always honor Retry-After.",
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "example": 0
          },
          "X-RateLimit-Reset": {
            "description": "When the key's current window resets, as a Unix timestamp in seconds.",
            "schema": {
              "type": "integer"
            },
            "example": 1793113445
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "success": false,
              "error": "Rate limit exceeded: 60 requests per minute per API key. Try again in 42 seconds.",
              "code": "RATE_LIMITED",
              "retryAfter": 42,
              "limit": 60,
              "resetsAt": "2026-10-27T15:04:05.000Z"
            }
          }
        }
      },
      "ServerError": {
        "description": "Something failed on our side. Deep Search and Standard Search refund the credits they took (error ends with \"Credits have been refunded.\"), and a search 500 also covers a temporary outage of the search service, so retry it after a short wait with exponential backoff. After a 500 from an upload or POST /lists, check reservedCredits on GET /credits (or GET /lists) for a job or list that was created before you retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "success": false,
              "error": "Search service temporarily unavailable. Credits have been refunded."
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "Temporarily unavailable, for example code PREVIEW_UNAVAILABLE when a match count can't be fetched. Please try again.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}