Release Date: December 22, 2025

Affected Endpoints: Property Search API, Property Lookup API

Overview

This release introduces two powerful new request options for the Property Search and Property Lookup APIs that give you control over which data is returned in responses:

Datasets: Request specific data sections (e.g., basic, valuation, owner, deed)
Custom Projections: Request specific individual fields using dot-notation paths

These features help reduce response payload sizes, improve API performance, and lower bandwidth costs for high-volume API consumers.

1. Datasets Request Option

What Changed

You can now specify which data sections (datasets) to include in Property API responses. This allows you to request only the data you need, reducing response sizes and improving performance.

How It Works

Add a datasets array to the options object in your request. Only the specified datasets will be returned in the response.

Property Lookup API Request Example (POST URL https://api.batchdata.com/api/v1/property/lookup/all-attributes):

{
  "requests": [
    {
      "address": {
        "street": "3828 Piermont Dr NE",
        "city": "Albuquerque",
        "state": "NM",
        "zip": "87111"
      }
    }
  ],
  "options": {
    "datasets": ["basic", "valuation", "owner"]
  }
}

Property Search API Request Example (POST URL https://api.batchdata.com/api/v1/property/search):

{
  "searchCriteria": {
    "query": "Phoenix, AZ",
    "building": {
      "bedrooms": { "min": 3, "max": 5 }
    }
  },
  "options": {
    "skip": 0,
    "take": 25,
    "datasets": ["basic", "valuation", "owner"]
  }
}

Response: The response will only include data from the basic, valuation, and owner datasets (*the cost per record will still be dictated by the datasets that are provisioned at the token-level). All other data sections (deed, mortgage, foreclosure, etc.) will be omitted.

Available Datasets

Dataset	Description
`basic`	Basic property identifiers, address, owner name, and basic geographic characteristics
`core`	Extended core property data (mutually exclusive with `basic`)
`batchrank`	BatchRank property scoring and intelligence
`contact`	Owner contact information
`deed`	Deed history and transfer records
`demographic`	Neighborhood demographic data
`foreclosure`	Foreclosure status and history
`listing`	Property listing information
`mortgage-liens`	Mortgage and lien records
`owner`	Summary of property owner's portfolio
`permit`	Building permit records
`quicklist`	Quicklist categorization flags
`valuation`	Property valuation and equity estimates

Important Notes

Mutually Exclusive: The basic and core datasets are mutually exclusive. You can only request one or the other, not both.
Default Behavior: If no datasets are specified, all datasets provisioned for your API token are returned.
Access Control: Requesting a dataset that does not exist, or one your API token is not provisioned for, rejects the request with a 400 status. See API Token Access Control.

2. Custom Projections Request Option

What Changed

You can now request specific individual fields using dot-notation paths. This provides fine-grained control over exactly which fields are returned, further reducing response payload sizes.

How It Works

Set projection to "custom" and provide a customProjection array with dot-notation field paths.

Property Lookup Request Example (POST /v1/property/lookup/all-attributes):

{
  "requests": [
    {
      "address": {
        "street": "3828 Piermont Dr NE",
        "city": "Albuquerque",
        "state": "NM",
        "zip": "87111"
      }
    }
  ],
  "options": {
    "projection": "custom",
    "customProjection": [
      "address.hash",
      "address.state",
      "owner.mailingAddress.city",
      "sale.amount",
      "legal.subdivision"
    ]
  }
}

Property Search Request Example (POST /v1/property/search):

{
  "searchCriteria": {
    "query": "Phoenix, AZ",
    "building": {
      "bedrooms": { "min": 3, "max": 5 }
    }
  },
  "options": {
    "skip": 0,
    "take": 25,
    "projection": "custom",
    "customProjection": [
      "address.hash",
      "address.state",
      "owner.mailingAddress.city",
      "sale.amount",
      "legal.subdivision"
    ]
  }
}

Response: The response will only include the specific fields you requested. All other fields will be omitted.

Custom Projection Syntax

Dot notation required: Paths must use dot notation to specify nested fields (e.g., address.hash, owner.mailingAddress.city)
Root-level objects not supported: You cannot request entire root-level objects like "address" or "owner". You must specify the nested field paths.
Required parameter: The customProjection array is required when projection is set to "custom"

Example Field Paths

Field Path	Description
`address.hash`	Property address hash identifier
`address.street`	Street address
`address.city`	City name
`address.state`	State abbreviation
`address.zipcode`	ZIP code
`owner.names`	Owner names
`owner.mailingAddress.street`	Owner mailing street address
`owner.mailingAddress.city`	Owner mailing city
`sale.amount`	Last sale amount
`sale.date`	Last sale date
`valuation.estimatedValue`	Estimated property value
`valuation.equityCurrentEstimatedBalance`	Estimated equity, in dollars
`legal.subdivision`	Subdivision name
`building.bedrooms`	Number of bedrooms
`building.bathrooms`	Number of bathrooms
`building.livingArea`	Living area square footage

3. Billing and Cost Information

Important: These Features Do Not Affect API Request Costs

The datasets and customProjection request options control which data is returned in the response, but they do not affect how the cost of the API request is calculated.

How Costs Are Calculated

Cost is based on your API token configuration, not your request parameters
The cost per property record is determined by the datasets your API token is provisioned for
Using datasets or customProjection to limit response data does not reduce the cost of the request

Example

If your API token is provisioned with basic, valuation, owner, and deed datasets:

You are charged for all four datasets per property record returned
Even if your request specifies "datasets": ["basic"], you are still charged for all four datasets
The datasets parameter only controls what data is returned, not what you are charged for

How to Control Costs

To control API costs, you must adjust the datasets assigned to your API token:

Provision a new API token with only the datasets you need
Use the new token for requests where you want reduced costs
Note: Once an API token is provisioned, the datasets assigned to it cannot be changed

4. API Token Access Control

How Access Control Works

BatchData API tokens are provisioned with a set of allowed datasets. The API enforces access control automatically:

Request Validation: A datasets value must exist and be allowed for your API token
Access Control Enforcement: Requesting a dataset that does not exist, or one your token is not provisioned for, rejects the entire request. Nothing is returned and no record is billed
Error Response: A 400 status is returned with a warnings array naming the specific dataset that was rejected

Access Control Examples

Token Allowed Datasets	Requested Datasets	Result
basic, valuation, owner	basic, valuation	200 — basic, valuation returned
basic, valuation	basic, valuation, owner	400 — rejected, owner not allowed
basic, valuation, owner, deed	(none specified)	200 — basic, valuation, owner, deed returned

Warning Response Format

When a requested dataset does not exist or is not allowed for your token, the request is rejected with a 400 status and a warnings array naming the issue:

{
  "status": {
    "code": 400,
    "text": "Bad Request",
    "message": "Invalid dataset values. The field must have atleast one value"
  },
  "warnings": [
    {
      "code": "dataset_not_allowed",
      "message": "The following datasets are not available for your token: owner. Please contact support to enable these datasets."
    }
  ]
}

Projection Access Control

Custom projection fields are also constrained to allowed datasets:

If a projection field belongs to a dataset not allowed for your token, the field is omitted
A warning may be included if requested projection fields were filtered

5. Combined Usage

You can use datasets and custom projections together for maximum control.

Property Lookup Example (POST /v1/property/lookup/all-attributes):

{
  "requests": [
    {
      "address": {
        "street": "3828 Piermont Dr NE",
        "city": "Albuquerque",
        "state": "NM",
        "zip": "87111"
      }
    }
  ],
  "options": {
    "datasets": ["listing", "core"],
    "projection": "custom",
    "customProjection": [
      "address.hash",
      "address.state",
      "listing.status",
      "listing.price"
    ]
  }
}

Property Search Example (POST /v1/property/search):

{
  "searchCriteria": {
    "query": "Phoenix, AZ",
    "listing": {
      "status": { "inList": ["Active", "Pending"] }
    }
  },
  "options": {
    "skip": 0,
    "take": 25,
    "datasets": ["listing", "core"],
    "projection": "custom",
    "customProjection": [
      "address.hash",
      "address.state",
      "listing.status",
      "listing.price"
    ]
  }
}

These requests:

Limit data to the listing and core datasets
Further limit fields to only address.hash, address.state, listing.status, and listing.price

Customer Impact

Before

Full property records returned for every request
No control over which data sections were included
Large response payloads, especially for bulk requests
Higher bandwidth costs for high-volume consumers

After

Request only the data you need
Significantly reduced response payload sizes
Improved API performance
Lower bandwidth costs
Fine-grained control with custom projections

Benefits

Reduced Payload Size: Only receive the data you need
Improved Performance: Smaller responses mean faster processing
Lower Bandwidth Costs: Significant savings for high-volume API consumers
Flexible Control: Choose between dataset-level or field-level granularity
Access Transparency: Clear warnings when requested data is filtered

Frequently Asked Questions

Datasets

Q: What happens if I don't specify any datasets? A: All datasets allowed for your API token are returned (existing behavior).

Q: Can I request both basic and core datasets? A: No. The basic and core datasets are mutually exclusive. You can only request one or the other.

Q: What if I request a dataset not allowed for my token? A: The entire request is rejected with a 400 status and a warnings array naming the dataset that is not available for your token.

Q: Will this break my existing integration? A: No. These are optional parameters. Existing requests without datasets or projections continue to work as before.

Custom Projections

Q: Can I request entire objects like "address" or "owner"? A: No. You must use dot-notation to specify nested fields (e.g., address.hash, owner.mailingAddress.city).

Q: What happens if I set projection to "custom" but don't provide customProjection? A: The customProjection array is required when projection is set to "custom".

Q: Are there limits on how many fields I can request? A: There is no specific limit, but requesting fewer fields improves performance.

Q: How do I know what field paths are available? A: Refer to the property response schema in the API documentation. Field paths correspond to the nested structure of the property object.

Support

If you have questions about these features or need assistance:

Documentation: developer.batchdata.com
Support Email: support@batchdata.com
API Status: status.batchdata.com

Technical Notes

Datasets Implementation

Datasets filter response data at the server level before transmission
Multiple datasets can be combined in a single request
The basic and core datasets are mutually exclusive

Custom Projections Implementation

Projections are applied after dataset filtering
Dot-notation paths map to the property response object structure
Invalid field paths are ignored (no error returned)
Fields outside allowed datasets are automatically filtered

Datasets and Custom Projections API Release Notes - December 2025

Overview

1. Datasets Request Option

What Changed

How It Works

Available Datasets

Important Notes

2. Custom Projections Request Option

What Changed

How It Works

Custom Projection Syntax

Example Field Paths

3. Billing and Cost Information

Important: These Features Do Not Affect API Request Costs

How Costs Are Calculated

Example

How to Control Costs

4. API Token Access Control

How Access Control Works

Access Control Examples

Warning Response Format

Projection Access Control

5. Combined Usage

Customer Impact

Before

After

Benefits

Frequently Asked Questions

Datasets

Custom Projections

Support

Technical Notes

Datasets Implementation

Custom Projections Implementation