Table of Contents
Authentication and Token Types
BatchData APIs will only respond to requests made from identified users or applications. To authenticate users/applications, BatchData makes use of OAuth 2.0 Authorization.
OAuth 2.0 Authorization uses security tokens which provide trusted identities to users/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: <YOUR_TOKEN>
Host: <HOST_NAME>
Content-Length: 181
{
<REQUEST_PARAMS>
}cURL Request Example
curl --request POST \
--url <API_ENDPOINT> \
--header 'Authorization: <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 defined in the Admin console 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.
Admin Console Defaults: The dataset options displayed will default to the selections defined in your Admin console. (Kindly get in touch with your Account Administrator/BatchData Sales team if you want certain datasets enabled/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 Admin console settings.
Previously Defined Datasets: If the datasets for the Property Lookup or Property Search endpoints were previously defined, you are not prevented from making any changes to the dataset selections.
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. Based on the permissions assigned and the datasets being pulled, you will be charged the relevant amount 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 PayG 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 you do not have a Permit Details API Subscription assigned from the Admin Panel, you cannot generate a server-side API token with permission to access the Permit Details API endpoint.
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.
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 |
List Builder | User-Controlled | Allows the user to select what datasets, including Contact Enrichment, are 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:
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
You will only be charged for a premium dataset if you specifically request it 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. |
Custom Pricing
All customers default to the standard PAYG (Pay As You Go) rates for all datasets.
Custom rates for Property Lookup and Property Search are defined using the "Enterprise Datasets" action in the Admin console.
Custom pricing for all other endpoints is managed using the "Custom Pricing For All Endpoints" action in the Admin console.
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 PayG 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. |
Pricing and Billing for Datasets
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.