Datasets and Custom Projections API Release Notes - December 2025

Release Date: December 22, 2025

Affected Endpoints: /property/search, /property/lookup/all-attributes

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 Request Example (POST /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 Request Example (POST /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. All other data sections (deed, mortgage, foreclosure, etc.) will be omitted.

Available Datasets

Dataset	Description
`basic`	Core property identifiers, address, and basic 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`	MLS listing information
`mortgage-liens`	Mortgage and lien records
`owner`	Property owner information
`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 allowed for your API token are returned.
Access Control: Only datasets that are both requested AND permitted for your API token will be included in the response.

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.equity`	Estimated equity
`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: Any combination of datasets can be requested
Access Control Enforcement: Only datasets that are both requested AND allowed for your API token are returned
Response Filtering: Datasets not permitted for your token are filtered out, even if requested
Warning Response: A warning is included in the response if requested datasets were filtered due to token permissions

Access Control Examples

Token Allowed Datasets	Requested Datasets	Returned Datasets	Warning
basic, valuation, owner	basic, valuation	basic, valuation	None
basic, valuation	basic, valuation, owner	basic, valuation	Yes - owner filtered
basic, valuation, owner, deed	(none specified)	basic, valuation, owner, deed	None

Warning Response Format

When requested datasets are filtered due to token permissions, a warnings array is included in the response:

{
  "status": {
    "code": 200,
    "msg": "OK"
  },
  "results": {
    "properties": [...],
    "warnings": [
      {
        "code": "warning_not_commissioned_dataset",
        "message": "Dataset 'owner' is not available for your API token"
      }
    ]
  }
}

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 dataset is filtered from the response, and a warning is included indicating the dataset 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

Introduction to the Property Search API

Property Subscription API Release Notes - December 2025

Set up Authentication and Tokens to Start Using BatchData APIs

Property Search MCP Tools Release Notes - January 2026

Property Search MCP Tools - Usage Guide