Ava Data API Reference

Deep Search

Looks up one person by name and returns their phones, emails and addresses, plus related people (relatives and associates) with their phone numbers.

Input: 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".

Cost: 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.

Example request

curl -X POST https://app.avadata.ai/api/v1/deep-search \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701"
  }'

Example response

{
  "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
  }
}

Request body — application/json

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 402, 403, 413, 429, 500. See error codes below.

Standard Search

Looks up one person by name and address and returns phones, emails or both, chosen with dataTypes.

Input: 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".

Cost: 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.

Example request

curl -X POST https://app.avadata.ai/api/v1/standard-search \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "dataTypes": [
      "phone",
      "email"
    ]
  }'

Example response

{
  "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
  }
}

Request body — application/json

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 402, 403, 413, 429, 500. See error codes below.

Upload CSV for bulk processing

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.

File: 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.

Columns: 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.

• Street address: address, street, street address
• First name: first name, firstname, first
• Last name: last name, lastname, last
• Full name, used only when the file has no first-name or no last-name column: name, full name, fullname, owner name, owner
• City: city
• State: state, st
• ZIP: zip, zipcode, zip code, postal code

Rows: 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.

Joining 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.

Cost: 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.

Retries: 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.

Example request

curl -X POST https://app.avadata.ai/api/v1/bulk/upload \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -F 'file=@leads.csv' \
  -F 'dataTypes=["phone","email"]'

Example response

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "lookupId": "xyz789",
    "recordCount": 497,
    "dataTypes": [
      "phone",
      "email"
    ],
    "creditsPerMatch": 2,
    "status": "processing",
    "skippedCount": 3,
    "skippedReason": "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": "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."
  }
}

Request body — multipart/form-data

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 402, 403, 413, 429, 500. See error codes below.

Check bulk job status

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).

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.

Example request

curl -X GET https://app.avadata.ai/api/v1/bulk/abc123-def456/status \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "status": "processing",
    "progress": 65,
    "estimatedSecondsRemaining": 120,
    "numRecords": 497,
    "numMatches": 312,
    "errorMessage": ""
  }
}

Parameters

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 401, 403, 404, 429, 500. See error codes below.

Download bulk job results

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.

Standard 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:

• Match Found: Yes or No.
• Phone 1 to Phone 6, each followed by Line Type 1 to Line Type 6 (for example Mobile or Landline).
• Mobile 1 to Mobile 3 and Landline 1 to Landline 3: the same numbers grouped by line type.
• Email 1, Email 2 and so on, when email was requested.

Empty 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).

Without 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.

Example request

curl -X GET "https://app.avadata.ai/api/v1/bulk/abc123-def456/download?layout=standard" \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "numRecords": 497,
    "numMatches": 312,
    "creditsCharged": 401,
    "columns": [
      "Owner Name",
      "Property ID",
      "Match Found",
      "Phone 1",
      "Line Type 1"
    ],
    "results": [
      {
        "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"
      }
    ]
  }
}

Parameters

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 403, 404, 429, 500. See error codes below.

Upload CSV to build ad audiences

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.

Access: 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).

File: 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.

Columns: headers are matched case-insensitively, ignoring surrounding spaces, against these exact names; other headers aren't used for matching.

• Email: email, e-mail, email address, emailaddress
• Phone: phone, phone number, phonenumber, mobile, cell, cell phone
• Street address: address, street, street address
• First name: first name, firstname, first
• Last name: last name, lastname, last
• Full name, used only when the file has neither a first-name nor a last-name column: full name, fullname, name, owner name, owner
• City: city
• State: state, st
• ZIP: zip, zipcode, zip code, postal code

The 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.

Cost: 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.

By uploading you confirm you have the right to use the list for advertising and will follow each ad platform's customer-list policies.

Example request

curl -X POST https://app.avadata.ai/api/v1/audience/upload \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -F 'file=@contacts.csv' \
  -F 'platforms=["facebook","google"]'

Example response

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "lookupId": "xyz789",
    "recordCount": 500,
    "platforms": [
      "facebook",
      "google"
    ],
    "creditsPerMatch": 2,
    "status": "processing",
    "message": "Processing 500 records. Use GET /api/v1/audience/abc123-def456/status to check progress."
  }
}

Request body — multipart/form-data

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 402, 403, 413, 429, 500. See error codes below.

Check Digital Matching job status

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.

Example request

curl -X GET https://app.avadata.ai/api/v1/audience/abc123-def456/status \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "status": "processing",
    "progress": 65,
    "numRecords": 500,
    "numMatches": 312,
    "creditsCharged": 624,
    "platforms": [
      "facebook",
      "google"
    ],
    "platformCounts": {
      "facebook": 298,
      "google": 305
    },
    "errorMessage": ""
  }
}

Parameters

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 401, 403, 404, 429, 500. See error codes below.

Download audience files

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:

• 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.
• 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.
• README.txt: how to upload each file.

Pass 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".

Example request

curl -X GET https://app.avadata.ai/api/v1/audience/abc123-def456/download \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -o audienceDownload.zip

Example response

By default a successful call returns application/zip — a file rather than a JSON body — so the request above writes it straight to disk with -o.

Parameters

Error responses: 400, 401, 403, 404, 429, 500. See error codes below.

Get filter options

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.

Example request

curl -X GET https://app.avadata.ai/api/v1/lists/filters \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "location": {
      "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"
      ]
    },
    "quicklists": [
      {
        "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": [
      "any",
      "all"
    ],
    "maxQuicklists": 10,
    "ownerTypes": [
      {
        "id": "individual",
        "label": "Individual"
      },
      {
        "id": "company",
        "label": "Company"
      },
      {
        "id": "trust",
        "label": "Trust"
      }
    ],
    "propertyTypes": [
      {
        "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": [
      {
        "id": "conventional",
        "label": "Conventional"
      },
      {
        "id": "fha",
        "label": "FHA"
      },
      {
        "id": "va",
        "label": "VA"
      }
    ],
    "lienTypes": [
      {
        "id": "federal-tax",
        "label": "Federal Tax Lien"
      },
      {
        "id": "state-tax",
        "label": "State Tax Lien"
      }
    ],
    "distressTiming": {
      "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"
        ]
      }
    },
    "filings": {
      "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"
      ]
    },
    "ranges": [
      {
        "field": "beds",
        "unit": "bedrooms"
      },
      {
        "field": "yearBuilt",
        "unit": "year"
      },
      {
        "field": "assessedValue",
        "unit": "US dollars (county assessed value)"
      }
    ],
    "maxRecordsLimit": 100000,
    "creditsPerRecord": 1,
    "columns": [
      {
        "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": 35
  }
}

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 401, 403, 429, 500. See error codes below.

Preview a list

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.

Example request

curl -X POST https://app.avadata.ai/api/v1/lists/preview \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "location": {
        "state": "AZ",
        "kind": "county",
        "values": [
          "Maricopa"
        ]
      },
      "quicklists": [
        "absentee-owner",
        "high-equity"
      ],
      "quicklistMatch": "all",
      "propertyTypes": [
        "single-family"
      ],
      "ranges": {
        "yearBuilt": {
          "min": 1960
        }
      }
    },
    "maxRecords": 500
  }'

Example response

{
  "success": true,
  "data": {
    "matchCount": 1842,
    "creditsPerRecord": 1,
    "maxRecordsLimit": 100000,
    "maxRecords": 500,
    "recordsToPull": 500,
    "estimatedCredits": 500,
    "creditsToReserve": 500
  }
}

Request body — application/json

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 403, 413, 429, 500, 503. See error codes below.

Create a list

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.

Example request

curl -X POST https://app.avadata.ai/api/v1/lists \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maricopa absentee high equity",
    "maxRecords": 500,
    "filters": {
      "location": {
        "state": "AZ",
        "kind": "county",
        "values": [
          "Maricopa"
        ]
      },
      "quicklists": [
        "absentee-owner",
        "high-equity"
      ],
      "quicklistMatch": "all",
      "propertyTypes": [
        "single-family"
      ],
      "ranges": {
        "yearBuilt": {
          "min": 1960
        }
      }
    }
  }'

Example response

{
  "success": true,
  "data": {
    "listId": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31",
    "name": "Maricopa absentee high equity",
    "type": "search",
    "status": "processing",
    "progress": 0,
    "recordCount": 0,
    "maxRecords": 500,
    "creditsReserved": 500,
    "creditsCharged": 0,
    "filters": {
      "location": {
        "state": "AZ",
        "kind": "county",
        "values": [
          "Maricopa"
        ]
      },
      "quicklists": [
        "absentee-owner",
        "high-equity"
      ],
      "quicklistMatch": "all",
      "propertyTypes": [
        "single-family"
      ],
      "loanTypes": [],
      "lienTypes": [],
      "ranges": {
        "yearBuilt": {
          "min": 1960
        }
      }
    },
    "errorMessage": null,
    "createdVia": "api",
    "createdAt": "2026-10-26T15:04:05.000Z",
    "updatedAt": "2026-10-26T15:04:05.000Z",
    "completedAt": null
  }
}

Parameters

Request body — application/json

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 402, 403, 409, 413, 429, 500. See error codes below.

List your lists

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.

Example request

curl -X GET https://app.avadata.ai/api/v1/lists \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "lists": [
      {
        "listId": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31",
        "name": "Maricopa absentee high equity",
        "type": "search",
        "status": "processing",
        "progress": 0,
        "recordCount": 0,
        "maxRecords": 500,
        "creditsReserved": 500,
        "creditsCharged": 0,
        "filters": {
          "location": {
            "state": "AZ",
            "kind": "county",
            "values": [
              "Maricopa"
            ]
          },
          "quicklists": [
            "absentee-owner",
            "high-equity"
          ],
          "quicklistMatch": "all",
          "propertyTypes": [
            "single-family"
          ],
          "loanTypes": [],
          "lienTypes": [],
          "ranges": {
            "yearBuilt": {
              "min": 1960
            }
          }
        },
        "errorMessage": null,
        "createdVia": "api",
        "createdAt": "2026-10-26T15:04:05.000Z",
        "updatedAt": "2026-10-26T15:04:05.000Z",
        "completedAt": null
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 12,
      "hasMore": false
    }
  }
}

Parameters

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 403, 429, 500. See error codes below.

Get a list

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.

Example request

curl -X GET https://app.avadata.ai/api/v1/lists/8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31 \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "listId": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31",
    "name": "Maricopa absentee high equity",
    "type": "search",
    "status": "processing",
    "progress": 0,
    "recordCount": 0,
    "maxRecords": 500,
    "creditsReserved": 500,
    "creditsCharged": 0,
    "filters": {
      "location": {
        "state": "AZ",
        "kind": "county",
        "values": [
          "Maricopa"
        ]
      },
      "quicklists": [
        "absentee-owner",
        "high-equity"
      ],
      "quicklistMatch": "all",
      "propertyTypes": [
        "single-family"
      ],
      "loanTypes": [],
      "lienTypes": [],
      "ranges": {
        "yearBuilt": {
          "min": 1960
        }
      }
    },
    "errorMessage": null,
    "createdVia": "api",
    "createdAt": "2026-10-26T15:04:05.000Z",
    "updatedAt": "2026-10-26T15:04:05.000Z",
    "completedAt": null
  }
}

Parameters

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 401, 403, 404, 429, 500. See error codes below.

Get list records

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.

Example request

curl -X GET https://app.avadata.ai/api/v1/lists/8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31/records \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "listId": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31",
    "columns": [
      "propStreet",
      "propCity",
      "propState",
      "propZip",
      "ownerName",
      "owner1First",
      "owner1Last",
      "owner2First",
      "owner2Last",
      "ownerOccupied",
      "mailStreet",
      "mailCity",
      "mailState",
      "mailZip",
      "beds",
      "baths",
      "sqft",
      "yearBuilt",
      "assessedValue",
      "quickListFlags"
    ],
    "records": [
      {
        "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"
        ]
      }
    ],
    "pagination": {
      "limit": 100,
      "offset": 0,
      "total": 500,
      "hasMore": true
    }
  }
}

Parameters

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 403, 404, 429, 500. See error codes below.

Download a list as CSV

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.

Example request

curl -X GET https://app.avadata.ai/api/v1/lists/8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31/download \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -o downloadList.csv

Example response

By default a successful call returns text/csv — a file rather than a JSON body — so the request above writes it straight to disk with -o.

Parameters

Error responses: 400, 401, 403, 404, 429, 500. See error codes below.

Skip trace a list

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.

Example request

curl -X POST https://app.avadata.ai/api/v1/lists/8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31/skip-trace \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "dataTypes": [
      "phone",
      "email"
    ]
  }'

Example response

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "listId": "8f14e45f-ea8e-4a3b-9d2c-1b7e6f0a9c31",
    "recordCount": 497,
    "skippedCount": 3,
    "dataTypes": [
      "phone",
      "email"
    ],
    "creditsPerMatch": 2,
    "maxCredits": 994,
    "status": "processing",
    "message": "Skip trace started. Track it with GET /bulk/{jobId}/status and download results with GET /bulk/{jobId}/download?format=csv once it completes."
  }
}

Parameters

Request body — application/json

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 402, 403, 404, 409, 413, 429, 500. See error codes below.

Check credit balance

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.

Example request

curl -X GET https://app.avadata.ai/api/v1/credits \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "subscriptionCredits": 3000,
    "walletCredits": 1500,
    "reservedCredits": 500,
    "totalCredits": 4500,
    "availableCredits": 4000,
    "subscriptionStatus": "active"
  }
}

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 401, 403, 404, 429, 500. See error codes below.

Get API usage

Free. Returns request counts plus a page of your recent requests, newest first.

Only 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.

Paging: 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.

Example request

curl -X GET https://app.avadata.ai/api/v1/usage \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

{
  "success": true,
  "data": {
    "stats": {
      "totalRequests": 1250,
      "totalCreditsUsed": 8400,
      "requestsToday": 45,
      "requestsThisMonth": 890
    },
    "recentActivity": [
      {
        "id": "4b8e2f6a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
        "endpoint": "/api/v1/deep-search",
        "method": "POST",
        "statusCode": 200,
        "creditsUsed": 10,
        "timestamp": "2026-10-26T15:04:05.123Z"
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "hasMore": false
    }
  }
}

Parameters

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Error responses: 400, 401, 403, 429, 500. See error codes below.