Table of Contents
Authentication and Token Types
BatchData APIs only respond to requests from identified users or applications. Each REST API request authenticates with a bearer token that you send in the Authorization header. The REST API does not use OAuth 2.0: it has no authorization flow and no client credentials grant. OAuth sign-in applies only to the BatchData MCP server. See OAuth Authentication for MCP Server.
Bearer tokens provide trusted identities to users and applications.
These tokens contain data that is validated by BatchData’s API upon request.
Send this token in your header to access our APIs as follows:
HTTP Request Example
POST <API_ENDPOINT> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>
Host: <HOST_NAME>
Content-Length: 181
{
<REQUEST_PARAMS>
}
cURL Request Example
curl --request POST \
--url <API_ENDPOINT> \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"requests": [
{
<REQUEST_PARAMS>
}
]
}'
BatchData offers three types of Bearer Tokens for authentication:
Server Side Token - Used for offline or server-side integration.
Client Side Token - Used for public front-end applications (mobile apps, web pages, or desktop applications).
Sandbox API Token - Used to simulate a real API request and return mock data without incurring charges.
Server Tokens (Creation and Datasets)
Server Tokens are the preferred token for integrating with BatchData APIs.
Important Note for Existing Accounts
As part of a system update, all existing tokens have been automatically updated to apply the default datasets configured for your account.
Creating a New Server Token with Datasets
To generate a server-side token, follow the steps below:
Log in to your BatchData account.
Click on the API Tokens (the key icon) on the left-hand side menu.
Under the "Server Side Tokens" section, click Add New Token.
In the "Add New Server Token" modal, enter a relevant name for your token.
Select the API endpoints (Permissions) for which you wish to use this token.
If you select the Property Search or Property Lookup endpoints, you will also be prompted to assign the datasets this token can access.
Click CREATE once you have named the token and selected the required permissions and datasets.
The API token will be generated and displayed in a new modal.
Copy and store this token immediately for safe keeping, as it will not be displayed again.
Dataset Assignment Logic
When selecting permissions for the Property API endpoints, you can select the primary dataset you'd like to access.
New Accounts: All new accounts default to only the Basic and Contact Enrichment datasets.
Account Defaults: The dataset options displayed will default to the datasets enabled for your account. (Get in touch with your Account Administrator or the BatchData Sales team if you want certain datasets enabled or disabled).
Available Datasets
You can assign standard datasets, as well as:
Contact Enrichment: This dataset is returned only if the API call to Property Lookup or Property Search includes the request parameter skiptrace = true.
Updating an Existing Token
All created tokens are listed, allowing you to update permissions or enable/disable them. To update, click the View/Update link next to the token.
Unassigned Datasets: If you are updating an existing token AND that token did not previously have datasets assigned to the Property Lookup or Property Search endpoints, you can now assign them. The options will default to the datasets enabled for your account.
Previously Defined Datasets: If datasets were already assigned to the Property Lookup or Property Search endpoints on that token, those dataset selections are locked and cannot be changed. You can still add or remove API endpoints (permissions) on an existing token, but the datasets provisioned on it are fixed. To use a different set of datasets, create a new token.
Token Management (Enable/Disable)
You should immediately disable a token if you suspect suspicious activity or wish to temporarily suspend its usage.
Disabling a Server Side API Token
Navigate to the API Tokens page (key icon).
Under "Server Side Tokens," locate the token you'd like to disable.
Click the Disable button next to the token.
In the confirmation popup, click Disable again to confirm.
Enabling a Disabled API Token
Locate the disabled token in the token list.
Click the Enable button next to the token.
In the popup window, click Enable again to enable the API token.
API Token Creation: PayGo or Subscription Plans
The process for generating an API token differs based on whether your account is under the Pay-As-You-Go (PayGo) access or a Subscription Plan.
PayGo Access
Under PayGo access, you can provision any datasets to the token being generated. You are charged based on the datasets provisioned on the token, not on the datasets you request at runtime. Each property record returned is billed at the per-record rate for the token's provisioned datasets, and the amount is deducted from your BatchData wallet balance.
Subscription Plans
Using a Property Data Subscription, you can only assign the datasets to the API token that you have subscribed to as add-on datasets on top of your Primary Subscription.
Limited Datasets: If a user has subscribed to Property Data Subscription with Listing Data as an add-on, they will only be able to generate API tokens with permissions to Property Data API endpoints and the Listing Data dataset.
Included Datasets: Quick Lists, Pre-foreclosure, and Mortgage Transaction datasets are included by default in a user's Primary Property Data Subscription.
Permissions Mismatch: If a user generates an API token with all dataset permissions under the PayGo model and later tries to use the same token after buying a Property Data Subscription without add-ons, they will receive an error that they do not have permissions to access the non-subscribed datasets.
Permit Details Subscription: If your account does not have a Permit Details API Subscription, you cannot generate a server-side API token with permission to access the Permit Details API endpoint. Contact the BatchData Sales team to add it.
Client Side Token
Client Tokens are created for additional security. With your Client Token, you can specify the domain URLs and IP Addresses allowed to make authenticated calls with your token.
Client Side Tokens are currently only available for the Address Auto-Complete endpoint.
To generate a client-side token, you can include the name of your token and add up to 10 domain URLs and/or IP Addresses.
Sandbox API Token
Sandbox API Tokens are used to simulate API requests. They return mock data and are useful for testing and development. API calls made using a sandbox token will not incur any cost.
The Sandbox API Token can be used to test all available endpoints. Sandbox responses are sample mock data whose values can vary between calls, and they are not shaped by the request options you send (for example datasets, showRequests, filters, or pagination). Use a production token to validate options-driven behavior. For more detail, see Sandbox API Tokens.
System Generated "Form Requests" Token
A system-generated token is automatically created for your account and is used when you utilize certain front-end services within BatchData.
The system generated "Form Requests" token is defined with access to all API endpoints and all available datasets.
However, when this token is used, the front-end applications that leverage it will control what datasets are ultimately returned:
Front-End Service | Dataset Control | Datasets Returned |
Bulk Property Lookup | User-Controlled | Allows the user to select what datasets, including Contact Enrichment, are returned. |
Single Property Lookup | System-Controlled | Only returns the basic property dataset. |
(Note: The ability for users to define what datasets to return when performing a single property lookup will be added in near future.)
Pricing and Billing for Datasets
API calls made using server-side and client-side tokens are chargeable. BatchData uses a consumption-based billing model for datasets:
How Per-Record Billing Works
Billing Model Rationale: The token-based per-record billing model provides predictable cost estimation and transparent usage reporting. You can accurately forecast API expenses based on expected property record volumes and your token's dataset provisioning. Usage reports clearly correlate charges to property records retrieved, making it simple to validate billing against actual usage and understand cost breakdowns.
Property Search and Property Lookup Billing: For these endpoints specifically, costs are determined by your token's provisioned dataset access rather than what data you request at runtime. Each property record returned costs the full per-record rate for all datasets your token is provisioned to access, regardless of runtime parameters like datasets or customProjection.
Dataset vs Runtime Selection: While you can use the datasets parameter in Property Search and Property Lookup API calls to specify which datasets to include in responses, billing is based on your token's full provisioned dataset access, not your runtime selection.
Per-Record Billing: Every property record returned from Property Search and Property Lookup endpoints incurs the full per-record rate for all datasets your token is provisioned to access. Requesting a subset of data through parameters does not reduce the per-record cost.
Cost Optimization Strategies:
Provision tokens with only datasets needed for your specific use case
Create multiple tokens with different dataset combinations for different application needs
Use sandbox tokens during development and testing to avoid charges
Plan your token dataset combinations carefully before production deployment
Runtime Parameter Benefits: While datasets and customProjection parameters don't reduce costs, they provide benefits such as smaller response payloads, reduced bandwidth usage, and simplified data handling in your application.
For detailed dataset descriptions and pricing information, see Datasets and Custom Projections.
Pricing Display
When determining the cost to show on the pricing page for the Property Lookup and Property Search API end-points, the cost will include all associated datasets, including the Contact Enrichment (if enabled for the account).
Actual Usage Charges
Every property record returned from Property Lookup or Property Search is billed at the per-record rate for all datasets provisioned on the token, regardless of the runtime datasets parameter. Two datasets are the exception: they are billed only when you explicitly request them in your API call:
Dataset | Charging Trigger |
Contact Enrichment | You will not be charged unless you make the Property Lookup and Property Search API requests using the URL request parameter skiptrace = true. |
Images | You will not be charged unless you request property images by setting the |
Custom Pricing
All customers default to the standard PayGo rates for all datasets.
Custom rates for Property Lookup and Property Search can be configured for your account. Contact the BatchData Sales team to arrange custom rates.
Custom pricing is also available for all other endpoints. Contact the BatchData Sales team for details.
Troubleshooting
Issue | Resolution |
403 Forbidden Error (Access Denied) | This usually means your API token lacks the necessary permissions or the required datasets for the API call you are making. Solution: Go to API Tokens, find your token, and click View/Update to ensure the token has the correct API endpoints and datasets assigned. |
Previous Token Stops Working After Subscription Change | If you move from a PayGo model to a Subscription, your existing tokens may lose permissions to datasets that are not included in your new subscription. Solution: Generate a new API token with only the permissions/datasets included in your current subscription. |
Need to immediately stop API access | If you suspect unauthorized usage or a breach, you should disable your token immediately. Solution: Navigate to the API Tokens page, locate the token, and click Disable. |
Missing Datasets during Token Creation | If a dataset is not visible during token creation, it may not be enabled for your entire account. Solution: Contact your Account Administrator (BatchData Sales team) to request that the dataset be enabled at the account level. |
High Charge for Property Lookups | If charges are higher than expected, you may be unintentionally pulling premium datasets. Solution: Review your API call parameters. Ensure you are NOT using the skiptrace = true parameter if you only need the Basic property data, as this parameter triggers the chargeable Contact Enrichment dataset. |