curl --request GET \
--url https://api.baselayer.com/searches/batch/{id} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.baselayer.com/searches/batch/{id}"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.baselayer.com/searches/batch/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.baselayer.com/searches/batch/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.baselayer.com/searches/batch/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.baselayer.com/searches/batch/{id}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.baselayer.com/searches/batch/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"state": "PENDING",
"created_at": "2023-11-07T05:31:56Z",
"progress": 0,
"completed_count": 1,
"total_count": 1,
"options": [
"Order.WebsiteAnalysis"
],
"warnings": [],
"export_csv_uri": "<string>",
"export_jsonl_uri": "<string>",
"report_version": 123,
"exports_generated_at": "2023-11-07T05:31:56Z",
"tin_matching_pending_count": 0,
"tin_matching_unresolved_count": 0,
"questionnaire": {
"kyb": {
"current_provider": "Middesk",
"new_applications_per_month": 500,
"avg_uw_time_hours": 24,
"avg_uw_time_minutes": 2,
"match_rate_pct": 25,
"approval_rate_pct": 72
},
"web_presence": {
"existing_workflow_step": true,
"current_provider": "Built in-house"
},
"liens": {
"current_provider": "LexisNexis"
},
"litigations": {
"current_provider": "LexisNexis"
}
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Get Search Batch
Retrieve a SearchBatch by ID and return it in SearchBatchResponse format.
The two TIN counts are computed per request rather than stored.
tin_matching_pending_count counts the batch’s searches still
inside the IRS TIN-match retry budget, so it falls as verdicts land;
while it is positive the batch’s exports are a provisional snapshot
that will be regenerated — exports_generated_at moves forward each
time — so a caller that cached a download should re-read this response
before trusting it.
It reaching zero means nothing is left to retry, NOT that every TIN
was verified. tin_matching_unresolved_count is the companion that
says how many rows FINISHED without a verdict and dropped out of the
retry pool (budget spent, retries disabled for the program, or the
search cancelled). Both come from one scan so they cannot disagree.
The two do not partition the batch’s TIN rows: a search that is still
running is in neither, because its TIN match has not been attempted to
a conclusion. On a COMPLETED batch two zeroes therefore do mean
every TIN was verified; on one still processing they mean only that
nothing has been given up on yet.
curl --request GET \
--url https://api.baselayer.com/searches/batch/{id} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.baselayer.com/searches/batch/{id}"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.baselayer.com/searches/batch/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.baselayer.com/searches/batch/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.baselayer.com/searches/batch/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.baselayer.com/searches/batch/{id}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.baselayer.com/searches/batch/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"state": "PENDING",
"created_at": "2023-11-07T05:31:56Z",
"progress": 0,
"completed_count": 1,
"total_count": 1,
"options": [
"Order.WebsiteAnalysis"
],
"warnings": [],
"export_csv_uri": "<string>",
"export_jsonl_uri": "<string>",
"report_version": 123,
"exports_generated_at": "2023-11-07T05:31:56Z",
"tin_matching_pending_count": 0,
"tin_matching_unresolved_count": 0,
"questionnaire": {
"kyb": {
"current_provider": "Middesk",
"new_applications_per_month": 500,
"avg_uw_time_hours": 24,
"avg_uw_time_minutes": 2,
"match_rate_pct": 25,
"approval_rate_pct": 72
},
"web_presence": {
"existing_workflow_step": true,
"current_provider": "Built in-house"
},
"liens": {
"current_provider": "LexisNexis"
},
"litigations": {
"current_provider": "LexisNexis"
}
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
Path Parameters
The unique identifier of the search batch to retrieve searches for.
"a3c16db9-52f0-4f67-9ce3-0fae6f9f3f31"
"3b7b12c4-12e4-4f2e-9b67-1a9e34339372"
Response
Successful Response
Represents a batch business search response.
For real-time progress updates during batch processing, subscribe to SSE events on the /events endpoint and listen for SearchBatch.progress events.
A batch's export artifacts are a point-in-time snapshot, stamped with
exports_generated_at. Some TIN (EIN) verifications are still resolving
against the IRS when that snapshot is taken, so a batch can finish with
verdicts still outstanding — tin_matching_pending_count says how many.
While that count is positive the exports are provisional: as each verdict
lands the batch's files and report are regenerated in place, and
exports_generated_at moves forward. Subscribe to
SearchBatch.exports_refreshed on the /events endpoint, or the
SearchBatch.updated webhook, to be told when a regeneration lands rather
than polling for it.
Once tin_matching_pending_count reaches zero the exports have settled —
but that is a statement about the retrying, not about the verdicts. A search
can run out of retry attempts, or belong to a program that has TIN-match
retries switched off, and it then leaves the pending count without ever
getting an answer. tin_matching_unresolved_count is how many such rows
the batch ended up with: they report a non-final TIN status in the exports
and will not change again.
Neither count includes a search that is still running, because such a row has
not attempted its TIN match to a conclusion yet. Both counts at zero
therefore means only "nothing is awaiting a retry and nothing has been given
up on" — read together with state, it means every TIN was verified on a
COMPLETED batch, and nothing more than "no verdict has been missed yet"
on one that is still PENDING or EXECUTING.
Unique identifier for the business search batch.
The name of the business search batch.
The current state of the business search batch.
PENDING, EXECUTING, COMPLETED, FAILED, CANCELLED The datetime the business search batch was created.
Processing progress from 0.0 to 1.0. Null if not yet started.
0 <= x <= 10
Number of rows that have been processed. Null if not yet started.
x >= 0Total number of rows to process. Null if not yet started.
x >= 0Optional features to enable during business search execution.
Order.WebsiteAnalysis, Order.NaicsPrediction, Order.Pep, Order.Enhanced ["Order.WebsiteAnalysis"]
Any warnings that occurred.
GCS URI for the pre-computed CSV export. Available after batch completion.
GCS URI for the pre-computed JSONL export. Available after batch completion.
Report schema version. Available after batch completion.
When the export artifacts above were generated. Null until the batch first exports. This moves forward whenever the exports are regenerated because late TIN verdicts changed the results, so compare it against the value you last downloaded to tell whether your copy is current.
How many of this batch's searches have concluded still awaiting a TIN verification verdict from the IRS AND will be retried to get one. A positive count means the exports are provisional: those rows report a pending TIN status today, and the files and report will be regenerated once the verdicts land. Zero means nothing is left to retry, so the exports will not change again on their own — it does NOT mean every TIN was verified. Rows whose retries ran out, or whose program has TIN-match retries switched off, leave this count without an answer; tin_matching_unresolved_count reports those. A search that is still running is in neither count, because its TIN match has not been attempted to a conclusion yet — so on a batch that has not reached COMPLETED, both counts can read zero with verifications still to come.
x >= 00
12
How many of this batch's searches supplied a TIN, finished without a verification verdict, and will not be retried for one — the retry attempts were used up, the program has TIN-match retries switched off, the search was cancelled, or it was made against a sandbox application. These rows are final at a non-matched status: waiting longer will not change them, and re-submitting the search is the only way to try again. Counted alongside tin_matching_pending_count rather than folded into it, because a batch can settle (pending zero) with unresolved rows still in it. A search that has not finished is in neither count — nothing has been given up on yet — so both reading zero on a batch that is still running does not mean every TIN was verified.
x >= 00
3
Data-test questionnaire answers submitted with the batch, if any.
Show child attributes
Show child attributes