AI-assisted business research API
Submit structured business details to the business research worker pool. Each business becomes a task. The API returns task IDs immediately; poll until the task is complete, then download its JSON result.
The customer-facing product name is AI-assisted business research. Existing
API paths and permission scopes keep ai-mode in their names.
The service uses the supplied business identity and location to research the matching legal entity and individual business locations. Results are returned as structured JSON, including the submitted details, registry status, company-number verification, location records, and an evidence-based data-quality assessment. A completed task's result is JSON data; it is not a claim that every field was found or independently verified.
Accuracy notice: AI-assisted business research results may be inaccurate, outdated, or incomplete. Independently verify important details against authoritative sources before relying on them, particularly for legal, financial, or compliance decisions. This service does not provide an official registry confirmation.
Before you start
- Sign in to the customer portal and create an API key.
- Set the key as the
API_KEYenvironment variable. Keep it private; do not commit it to source control.
Examples use https://bankworks.info as the API base URL.
Python requires requests (pip install requests).
The Node.js example uses built-in fetch, needs Node 18 or newer,
and should be saved as an ES module such as ai_mode.mjs.
The cURL example also uses jq to read JSON fields.
export API="https://bankworks.info"
export API_KEY="your-api-key"
Load API_KEY from your secret manager in production.
Each POST creates new tasks; poll an existing task while it is still running.
Resubmitting creates a new task and may incur another charge.
Request fields
Send between 1 and 100 entities in one request. The first three fields
are required. address is a free-text location field: include
any available street, city, region, or postal code in one string.
companyNumber is optional and represents the provided corporate
registration or tax number. telephone is optional and provides
a business phone number as a research clue. The current raw result has no
dedicated phone-verification block; see the result-field notes below.
Set the top-level mode to control how much of the result the
result endpoint returns. regular includes the submitted entity,
requested-location status, company-number and telephone verification, and data quality.
advance also includes the parent company and business locations.
premium returns the complete JSON result. If omitted,
mode defaults to regular. The same mode applies to
every entity in the request and is shown as task.resultMode when
polling task status. The selected mode also determines the applicable
mode-specific quota and rate; it does not change worker routing.
The sample business details below are entirely fictional.
| JSON field | Required | Meaning | Maximum |
|---|---|---|---|
mode | No | regular, advance, or premium; controls result detail | One value per request |
businessName | Yes | Business or group name | 500 characters |
address | Yes | Address, city, region, and/or postal code as supplied | 1,000 characters |
country | Yes | Country where the business is located | 200 characters |
companyNumber | No | Provided corporate ID or tax number; use null or omit it when unknown | 200 characters |
telephone | No | Provided business telephone; AI Mode checks whether it is current and may return a verified replacement | 200 characters |
Complete example
Pick a language tab. Each complete example submits two fictional businesses
in one request, polls each task, and saves each returned JSON to a local file.
One request accepts 1–100 businesses; each entry creates a separate task.
The cURL example requires jq.
import os
import time
from pathlib import Path
import requests
API = os.environ.get("API", "https://bankworks.info")
API_KEY = os.environ["API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}
created = requests.post(
f"{API}/v1/ai-mode/tasks",
headers=headers,
json={"mode": "regular", "entities": [
{
"businessName": "BLUE COMET PAPERWORK LAB (FICTIONAL)",
"address": "42 Imaginary Lane, Sample City, ZZ 00000",
"country": "Fictionland",
"companyNumber": "FICTIONAL-0001",
"telephone": "+1 202 555 0101",
},
{
"businessName": "MOON LANTERN DESIGN HOUSE (FICTIONAL)",
"address": "8 Paper Street, Example Bay, YY 11111",
"country": "Fictionland",
},
]},
timeout=30,
)
created.raise_for_status()
job = created.json()
task_ids = job["taskIds"]
print(f"Created {len(task_ids)} tasks")
for index, task_id in enumerate(task_ids, start=1):
while True:
status_response = requests.get(
f"{API}/v1/ai-mode/tasks/{task_id}", headers=headers, timeout=30,
)
status_response.raise_for_status()
task = status_response.json()["task"]
if task["status"] == "DONE" and task["resultAvailable"]:
break
if task["status"] in {"FAILED", "CANCELLED"}:
print(f"Task {task_id} {task['status']}: {task.get('error', 'no details')}")
break
time.sleep(5)
if task["status"] != "DONE" or not task["resultAvailable"]:
continue
result = requests.get(
f"{API}/v1/ai-mode/tasks/{task_id}/result", headers=headers, timeout=60,
)
result.raise_for_status()
output = Path(f"ai-searching-{index}-{task_id}.json")
output.write_bytes(result.content)
print("Saved JSON to", output)
import { writeFile } from "node:fs/promises";
import { setTimeout as delay } from "node:timers/promises";
const API = process.env.API || "https://bankworks.info";
const API_KEY = process.env.API_KEY;
if (!API_KEY) throw new Error("Set API_KEY first");
const headers = { Authorization: "Bearer " + API_KEY };
const created = await fetch(API + "/v1/ai-mode/tasks", {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({ mode: "regular", entities: [
{
businessName: "BLUE COMET PAPERWORK LAB (FICTIONAL)",
address: "42 Imaginary Lane, Sample City, ZZ 00000",
country: "Fictionland",
companyNumber: "FICTIONAL-0001",
telephone: "+1 202 555 0101",
},
{
businessName: "MOON LANTERN DESIGN HOUSE (FICTIONAL)",
address: "8 Paper Street, Example Bay, YY 11111",
country: "Fictionland",
},
] }),
});
if (!created.ok) throw new Error(created.status + ": " + await created.text());
const job = await created.json();
console.log("Created tasks:", job.taskIds.length);
for (const [index, taskId] of job.taskIds.entries()) {
let task;
while (true) {
const response = await fetch(API + "/v1/ai-mode/tasks/" + taskId, { headers });
if (!response.ok) throw new Error(response.status + ": " + await response.text());
task = (await response.json()).task;
if (task.status === "DONE" && task.resultAvailable) break;
if (["FAILED", "CANCELLED"].includes(task.status)) {
console.error("Task", taskId, task.status + ":", task.error || "no details");
break;
}
await delay(5000);
}
if (task.status !== "DONE" || !task.resultAvailable) continue;
const result = await fetch(API + "/v1/ai-mode/tasks/" + taskId + "/result", { headers });
if (!result.ok) throw new Error(result.status + ": " + await result.text());
const output = "ai-searching-" + (index + 1) + "-" + taskId + ".json";
await writeFile(output, Buffer.from(await result.arrayBuffer()));
console.log("Saved JSON to", output);
}
: "${API_KEY:?Set API_KEY first}"
API="${API:-https://bankworks.info}"
CREATED="$(curl --fail --silent --show-error \
-X POST "$API/v1/ai-mode/tasks" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode":"regular","entities":[{"businessName":"BLUE COMET PAPERWORK LAB (FICTIONAL)","address":"42 Imaginary Lane, Sample City, ZZ 00000","country":"Fictionland","companyNumber":"FICTIONAL-0001","telephone":"+1 202 555 0101"},{"businessName":"MOON LANTERN DESIGN HOUSE (FICTIONAL)","address":"8 Paper Street, Example Bay, YY 11111","country":"Fictionland"}]}')"
TASK_IDS="$(printf '%s' "$CREATED" | jq -r '.taskIds[]')"
printf 'Created %s tasks\n' "$(printf '%s\n' "$TASK_IDS" | wc -l | tr -d ' ')"
INDEX=0
for TASK_ID in $TASK_IDS; do
INDEX=$((INDEX + 1))
while true; do
STATUS_JSON="$(curl --fail --silent --show-error \
-H "Authorization: Bearer $API_KEY" \
"$API/v1/ai-mode/tasks/$TASK_ID")"
STATUS="$(printf '%s' "$STATUS_JSON" | jq -r '.task.status')"
RESULT_AVAILABLE="$(printf '%s' "$STATUS_JSON" | jq -r '(.task.resultAvailable == true) or (.task.resultAvailable == 1)')"
if [ "$STATUS" = "DONE" ] && [ "$RESULT_AVAILABLE" = "true" ]; then break; fi
case "$STATUS" in
FAILED|CANCELLED) printf 'Task %s failed: %s\n' "$TASK_ID" "$(printf '%s' "$STATUS_JSON" | jq -r '.task.error // "no details"')"; break ;;
esac
sleep 5
done
if [ "$STATUS" != "DONE" ] || [ "$RESULT_AVAILABLE" != "true" ]; then continue; fi
OUTPUT="ai-searching-$INDEX-$TASK_ID.json"
curl --fail --silent --show-error \
-H "Authorization: Bearer $API_KEY" \
"$API/v1/ai-mode/tasks/$TASK_ID/result" \
-o "$OUTPUT"
printf 'Saved JSON to %s\n' "$OUTPUT"
done
Track a task
The submit response includes jobId, a taskIds
array, taskCount, dispatched, and
duplicate. Save a task ID and poll
GET /v1/ai-mode/tasks/{taskId}. The status response wraps
details in a task object; when task.status is
DONE and task.resultAvailable indicates the result
is available (it may be encoded as boolean true or number
1), fetch the result. While the task is queued or running, wait a few seconds before
polling again. A worker can claim it only after completing all four
current setup prompts.
{
"ok": true,
"task": {
"taskId": "TASK_ID",
"status": "DONE",
"resultAvailable": true
}
}
Download the JSON
The result endpoint returns the stored JSON as an attachment. Save the response body to a file on the machine running your client.
Understand the JSON result
The response uses the schema below. Every company, identifier, address,
source, and contact detail is invented for this example; it does not
describe a real business or research result. Most fields are populated so
you can see the shape of a complete response. The actual result can have
multiple entries in businessLocations when separate businesses
are supported by the research.
Use the tabs to compare the result returned for each mode. Regular and
Advance are projections of the research result; Premium returns the raw
research JSON, including the company,
location-match, and field-level evidence records explained below. The
source URLs, identifiers, and company details in these examples are fictional.
Omitted optional fields and null values are normal in real results.
All three tabs describe the same fictional business, so shared facts have the same values. The difference is which fields the download exposes:
| Mode | Fields returned in addition to the previous mode |
|---|---|
| Regular | Submitted identity and location status, business profile, source summaries, company-number and telephone verification, and data quality. |
| Advance | Everything in Regular, plus a parent-company summary, ownership and control, and business-location summaries with addresses and contacts. |
| Premium | The complete raw result: outcome status/error, distinct companies[], exact subjectMatch, per-field fieldSources, financial data, and detailed location identifiers, relocation, maps, and marketplace profiles. |
{
"submittedEntity": {
"providedDetails": {
"businessName": "AURORA CRAFT SYSTEMS (FICTIONAL)",
"street": "17 Example Row",
"postalCode": "EX 2048",
"city": "Sampleville",
"country": "Example Republic",
"companyNumber": "EXAMPLE-REG-2048",
"telephone": null
},
"requestedLocationStatus": {
"status": "ACTIVE",
"registryAction": null,
"statusEffectiveDate": null,
"relocation": null
}
},
"businessProfile": {
"description": "Fictional maker of custom stationery and paper goods.",
"productsAndServices": [
"Custom notebooks",
"Small-batch printing"
],
"industryCodes": [
{
"system": "EXAMPLE",
"code": "EX-1812",
"label": "Fictional printing services"
}
]
},
"sources": [
{
"sourceName": "Example Registry (FICTIONAL)",
"sourceType": "OFFICIAL_REGISTRY",
"sourceUrl": "https://registry.example/company/EXAMPLE-REG-2048",
"accessedAt": "2026-11-05T10:30:00Z",
"supports": [
"Company and site identifiers, legal status, registered-office flag, and parent relationship in this fictional example."
]
},
{
"sourceName": "Aurora Craft website (FICTIONAL)",
"sourceType": "COMPANY_WEBSITE",
"sourceUrl": "https://aurora-craft.example/about",
"accessedAt": "2026-11-05T10:31:00Z",
"supports": [
"Public business name, address, website, and products in this fictional example."
]
}
],
"companyNumberVerification": {
"providedCompanyNumber": "EXAMPLE-REG-2048",
"verificationStatus": "VALID",
"resolvedCompanyNumber": "EXAMPLE-REG-2048",
"resolutionNotes": "Illustrative match in this fictional example."
},
"telephoneVerification": {
"providedTelephone": null,
"verificationStatus": null,
"resolvedTelephone": null,
"resolutionNotes": null
},
"dataQuality": {
"confidenceLevel": "HIGH",
"confidenceScore": 85,
"assessmentReason": "Illustrative only: the example sources and identifiers are fictional.",
"checkedAt": "2026-11-05T10:32:00Z"
}
}
{
"submittedEntity": {
"providedDetails": {
"businessName": "AURORA CRAFT SYSTEMS (FICTIONAL)",
"street": "17 Example Row",
"postalCode": "EX 2048",
"city": "Sampleville",
"country": "Example Republic",
"companyNumber": "EXAMPLE-REG-2048",
"telephone": null
},
"requestedLocationStatus": {
"status": "ACTIVE",
"registryAction": null,
"statusEffectiveDate": null,
"relocation": null
}
},
"businessProfile": {
"description": "Fictional maker of custom stationery and paper goods.",
"productsAndServices": [
"Custom notebooks",
"Small-batch printing"
],
"industryCodes": [
{
"system": "EXAMPLE",
"code": "EX-1812",
"label": "Fictional printing services"
}
]
},
"sources": [
{
"sourceName": "Example Registry (FICTIONAL)",
"sourceType": "OFFICIAL_REGISTRY",
"sourceUrl": "https://registry.example/company/EXAMPLE-REG-2048",
"accessedAt": "2026-11-05T10:30:00Z",
"supports": [
"Company and site identifiers, legal status, registered-office flag, and parent relationship in this fictional example."
]
},
{
"sourceName": "Aurora Craft website (FICTIONAL)",
"sourceType": "COMPANY_WEBSITE",
"sourceUrl": "https://aurora-craft.example/about",
"accessedAt": "2026-11-05T10:31:00Z",
"supports": [
"Public business name, address, website, and products in this fictional example."
]
}
],
"parentCompany": {
"legalName": "AURORA IMAGINARY HOLDINGS LTD (FICTIONAL)",
"companyRegistrationNumber": "EXAMPLE-HOLDCO-2048",
"currentSiteStatus": "ACTIVE"
},
"ownershipAndControl": {
"beneficialOwners": [],
"directors": []
},
"companyNumberVerification": {
"providedCompanyNumber": "EXAMPLE-REG-2048",
"verificationStatus": "VALID",
"resolvedCompanyNumber": "EXAMPLE-REG-2048",
"resolutionNotes": "Illustrative match in this fictional example."
},
"telephoneVerification": {
"providedTelephone": null,
"verificationStatus": null,
"resolvedTelephone": null,
"resolutionNotes": null
},
"businessLocations": [
{
"brandOrDepartmentName": "Harbor Studio (FICTIONAL)",
"publicName": "AURORA CRAFT SYSTEMS (FICTIONAL)",
"companyRegistrationNumber": "EXAMPLE-REG-2048",
"locationRegistrationNumber": "EXAMPLE-SITE-2048-01",
"vatNumber": null,
"franchiseType": "INDEPENDENT",
"organizationType": "SECONDARY_ESTABLISHMENT",
"parentCompanyName": "AURORA IMAGINARY HOLDINGS LTD (FICTIONAL)",
"networkName": null,
"businessStartDate": "2020-03-12",
"businessEndDate": null,
"operatingStatus": "ACTIVE",
"industry": "Custom stationery and paper goods",
"address": {
"streetNumber": "17",
"streetName": "Example Row",
"city": "Sampleville",
"postalCode": "EX 2048",
"region": null,
"country": "Example Republic"
},
"contact": {
"internationalPhone": null,
"localPhone": null,
"website": "https://aurora-craft.example"
},
"serviceAreas": [
"Sampleville"
]
}
],
"dataQuality": {
"confidenceLevel": "HIGH",
"confidenceScore": 85,
"assessmentReason": "Illustrative only: the example sources and identifiers are fictional.",
"checkedAt": "2026-11-05T10:32:00Z"
}
}
{
"contractVersion": "business-research.v2",
"status": "COMPLETED",
"error": {
"code": null,
"message": null
},
"submittedEntity": {
"providedDetails": {
"businessName": "AURORA CRAFT SYSTEMS (FICTIONAL)",
"street": "17 Example Row",
"postalCode": "EX 2048",
"city": "Sampleville",
"country": "Example Republic",
"companyNumber": "EXAMPLE-REG-2048"
},
"requestedLocationStatus": {
"status": "ACTIVE",
"registryAction": null,
"statusEffectiveDate": null,
"relocation": null
}
},
"businessProfile": {
"description": "Fictional maker of custom stationery and paper goods.",
"productsAndServices": [
"Custom notebooks",
"Small-batch printing"
],
"industryCodes": [
{
"system": "EXAMPLE",
"code": "EX-1812",
"label": "Fictional printing services"
}
]
},
"parentCompany": {
"legalName": "AURORA IMAGINARY HOLDINGS LTD (FICTIONAL)",
"companyRegistrationNumber": "EXAMPLE-HOLDCO-2048",
"currentSiteStatus": "ACTIVE"
},
"ownershipAndControl": {
"beneficialOwners": [],
"directors": []
},
"companyNumberVerification": {
"providedCompanyNumber": "EXAMPLE-REG-2048",
"verificationStatus": "VALID",
"resolvedCompanyNumber": "EXAMPLE-REG-2048",
"resolutionNotes": "Illustrative match in this fictional example."
},
"businessLocations": [
{
"locationKey": "loc1",
"brandOrDepartmentName": "Harbor Studio (FICTIONAL)",
"publicName": "AURORA CRAFT SYSTEMS (FICTIONAL)",
"companyRegistrationNumber": "EXAMPLE-REG-2048",
"companyRegistrationCountryCode": "EX",
"locationRegistrationNumber": "EXAMPLE-SITE-2048-01",
"identifierVerified": true,
"identifierSource": "OFFICIAL_REGISTRY",
"identifierSourceId": "s1",
"vatNumber": null,
"franchiseType": "INDEPENDENT",
"organizationType": "SECONDARY_ESTABLISHMENT",
"isRegisteredOffice": false,
"parentCompanyName": "AURORA IMAGINARY HOLDINGS LTD (FICTIONAL)",
"networkName": null,
"businessStartDate": "2020-03-12",
"businessEndDate": null,
"relocation": {
"previousLocationRegistrationNumber": null,
"successorLocationRegistrationNumber": null,
"relocationDate": null
},
"operatingStatus": "ACTIVE",
"industry": "Custom stationery and paper goods",
"address": {
"streetNumber": "17",
"streetName": "Example Row",
"city": "Sampleville",
"postalCode": "EX 2048",
"region": null,
"country": "Example Republic"
},
"coordinates": {
"latitude": null,
"longitude": null
},
"contact": {
"internationalPhone": null,
"localPhone": null,
"website": "https://aurora-craft.example"
},
"serviceAreas": [
"Sampleville"
],
"googleMaps": {
"placeId": null,
"cid": null
},
"marketplaceProfiles": []
}
],
"subjectMatch": {
"matchedLocationKey": "loc1",
"matchedLocationRegistrationNumber": "EXAMPLE-SITE-2048-01",
"matchedCompanyRegistrationNumber": "EXAMPLE-REG-2048",
"matchBasis": [
"ADDRESS",
"NAME"
],
"matchConfidence": "HIGH"
},
"companies": [
{
"companyRegistrationNumber": "EXAMPLE-REG-2048",
"companyRegistrationCountryCode": "EX",
"legalStatus": "ACTIVE",
"statusEffectiveDate": null,
"statusSourceId": "s1",
"parentCompany": {
"legalName": "AURORA IMAGINARY HOLDINGS LTD (FICTIONAL)",
"companyRegistrationNumber": "EXAMPLE-HOLDCO-2048",
"companyRegistrationCountryCode": "EX",
"relationshipType": "PARENT",
"ownershipPercent": null,
"sourceId": "s1"
}
}
],
"financialProfile": {
"latestAccounts": {
"periodEnd": null,
"currency": null,
"revenue": null,
"operatingProfit": null,
"totalAssets": null,
"totalLiabilities": null,
"employeeCount": null
}
},
"sources": [
{
"sourceId": "s1",
"sourceName": "Example Registry (FICTIONAL)",
"sourceType": "OFFICIAL_REGISTRY",
"registryAuthority": "EXAMPLE_REGISTRY",
"sourceUrl": "https://registry.example/company/EXAMPLE-REG-2048",
"accessedAt": "2026-11-05T10:30:00Z",
"supports": [
"Company and site identifiers, legal status, registered-office flag, and parent relationship in this fictional example."
]
},
{
"sourceId": "s2",
"sourceName": "Aurora Craft website (FICTIONAL)",
"sourceType": "COMPANY_WEBSITE",
"registryAuthority": null,
"sourceUrl": "https://aurora-craft.example/about",
"accessedAt": "2026-11-05T10:31:00Z",
"supports": [
"Public business name, address, website, and products in this fictional example."
]
}
],
"fieldSources": {
"companies[0].legalStatus": [
"s1"
],
"businessLocations[0].companyRegistrationNumber": [
"s1"
],
"businessLocations[0].locationRegistrationNumber": [
"s1"
],
"businessLocations[0].operatingStatus": [
"s1"
],
"businessLocations[0].isRegisteredOffice": [
"s1"
],
"subjectMatch.matchedLocationRegistrationNumber": [
"s1",
"s2"
],
"subjectMatch.matchedCompanyRegistrationNumber": [
"s1"
],
"businessLocations[0].contact.website": [
"s2"
]
},
"dataQuality": {
"confidenceLevel": "HIGH",
"confidenceScore": 85,
"assessmentReason": "Illustrative only: the example sources and identifiers are fictional.",
"checkedAt": "2026-11-05T10:32:00Z"
}
}
Field meanings
Each tab shows only the fields added by that mode compared with the previous one.
| Field | Meaning |
|---|---|
| REGULAR · Core fields | |
submittedEntity | The business and location submitted for research, with the result for that requested location. |
submittedEntity.providedDetails | The original input values, preserved so the result can be matched to the submitted entity. |
submittedEntity.providedDetails.businessName | Business or group name as supplied by the caller. |
submittedEntity.providedDetails.street | Street portion of the supplied address, when it can be separated. |
submittedEntity.providedDetails.postalCode | Postal or ZIP code from the supplied address, when available. |
submittedEntity.providedDetails.city | City from the supplied address, when available. |
submittedEntity.providedDetails.country | Country supplied for the business. |
submittedEntity.providedDetails.companyNumber | Corporate or tax number supplied by the caller; null when none was provided. |
submittedEntity.providedDetails.telephone | Caller-supplied phone when the underlying research result includes it; otherwise the Regular/Advance projection uses null. |
submittedEntity.requestedLocationStatus | Registry status and any relocation information for the exact submitted location. |
submittedEntity.requestedLocationStatus.status | ACTIVE, CLOSED, MOVED, or UNKNOWN for the requested location. |
submittedEntity.requestedLocationStatus.registryAction | Relevant registry action or event behind the status, when supported by evidence. |
submittedEntity.requestedLocationStatus.statusEffectiveDate | Date the status or registry action took effect, formatted as YYYY-MM-DD. |
submittedEntity.requestedLocationStatus.relocation | Relocation details when the requested location is marked MOVED; otherwise null. |
submittedEntity.requestedLocationStatus.relocation.movedWithinSameCountry | Whether evidence indicates the business moved within the same country. |
submittedEntity.requestedLocationStatus.relocation.newAddress | Structured destination address after a move. |
submittedEntity.requestedLocationStatus.relocation.newAddress.streetNumber | House or building number at the new address. |
submittedEntity.requestedLocationStatus.relocation.newAddress.streetName | Street name at the new address. |
submittedEntity.requestedLocationStatus.relocation.newAddress.city | City at the new address. |
submittedEntity.requestedLocationStatus.relocation.newAddress.postalCode | Postal or ZIP code at the new address. |
submittedEntity.requestedLocationStatus.relocation.newAddress.region | State, province, or region at the new address. |
submittedEntity.requestedLocationStatus.relocation.newAddress.country | Country at the new address. |
companyNumberVerification | Comparison of the submitted company number with the resolved entity and registry evidence. |
companyNumberVerification.providedCompanyNumber | Company number supplied by the caller. |
companyNumberVerification.verificationStatus | VALID, INVALID_OR_NOT_FOUND, NOT_PROVIDED, or UNKNOWN. |
companyNumberVerification.resolvedCompanyNumber | Official number resolved for the matching company, if available. |
companyNumberVerification.resolutionNotes | Short explanation of the number match, mismatch, or resolution. |
telephoneVerification | Projected phone-verification fields. They may all be null because the raw result does not define this object. |
telephoneVerification.providedTelephone | Caller-supplied telephone if the underlying result preserved it; otherwise null. |
telephoneVerification.verificationStatus | VALID, INVALID_OR_OUTDATED, UNVERIFIABLE, or NOT_PROVIDED. |
telephoneVerification.resolvedTelephone | Current business telephone confirmed by reliable public evidence, if available. |
telephoneVerification.resolutionNotes | Short evidence-based explanation of the match, mismatch, or inability to verify. |
businessProfile | Concise customer-facing description of the business and its activity. |
businessProfile.description | Factual summary of what the business does. |
businessProfile.productsAndServices | Products and services supported by the sources. |
businessProfile.industryCodes | Industry classification codes with their system, code, and label. |
businessProfile.industryCodes[].system | Classification system used for the industry code. |
businessProfile.industryCodes[].code | Code assigned by that classification system. |
businessProfile.industryCodes[].label | Readable industry description for the code. |
sources | Sources actually consulted to support the result, shared by every mode. |
sources[].sourceName | Name of the registry, website, profile, or publication consulted. |
sources[].sourceType | Source category: official registry, commercial aggregator, company website, maps, directory, business profile, news, or other. |
sources[].sourceUrl | Exact HTTP(S) page URL when available; otherwise null. The worker converts non-URL source references to null. |
sources[].accessedAt | UTC timestamp when the source was checked. |
sources[].supports | Plain-language facts supported by this source; JSON paths belong in fieldSources. |
dataQuality | Summary of how complete and consistent the evidence is for this result. |
dataQuality.confidenceLevel | HIGH, MEDIUM, LOW, or UNKNOWN for overall evidence strength. |
dataQuality.confidenceScore | Evidence-based integer from 0 to 100; it is not a statistically measured probability. |
dataQuality.assessmentReason | Explanation of the evidence and any uncertainty behind the quality assessment. |
dataQuality.checkedAt | UTC timestamp when this research result was assembled. |
| ADVANCE · Additional fields beyond Regular | |
parentCompany | Top-level parent summary. For a response with multiple companies, use each companies[].parentCompany in Premium to avoid assigning one company's parent to another. |
parentCompany.legalName | Parent company's legal name. |
parentCompany.companyRegistrationNumber | Parent company's official registration number. |
parentCompany.currentSiteStatus | Current status of the parent company's site: ACTIVE, CLOSED, MOVED, or UNKNOWN. |
ownershipAndControl | Publicly supported beneficial ownership and director information. |
ownershipAndControl.beneficialOwners | People publicly identified as owning or controlling the entity. |
ownershipAndControl.beneficialOwners[].name | Publicly listed beneficial owner name. |
ownershipAndControl.beneficialOwners[].ownershipPercent | Ownership percentage when explicitly stated by a reliable source; otherwise null. |
ownershipAndControl.beneficialOwners[].controlType | Evidence-based description of how the person owns or controls the entity. |
ownershipAndControl.directors | Publicly listed directors or equivalent company officers. |
ownershipAndControl.directors[].name | Publicly listed director or officer name. |
ownershipAndControl.directors[].role | Role held by that person in the company. |
ownershipAndControl.directors[].appointedDate | Appointment date when available. |
ownershipAndControl.directors[].resignedDate | Resignation date when available; otherwise null. |
businessLocations | Array of returned sites or brand items, including relevant branches or other companies when supported; may be empty or contain multiple entries. |
businessLocations[].brandOrDepartmentName | Brand or department name associated with this location. |
businessLocations[].publicName | Name used publicly by this business location. |
businessLocations[].companyRegistrationNumber | Registration number of the company operating this location. |
businessLocations[].locationRegistrationNumber | Registration identifier specific to the branch or location. |
businessLocations[].vatNumber | VAT registration number for this business, when available. |
businessLocations[].franchiseType | FRANCHISE or INDEPENDENT when evidence supports a classification. |
businessLocations[].organizationType | HEADQUARTERS, BRANCH, SECONDARY_ESTABLISHMENT, UNKNOWN, or null; this classifies the establishment, not its legal company form. |
businessLocations[].parentCompanyName | Name of the parent company associated with this location. |
businessLocations[].networkName | Dealer group, franchise network, or other business network name. |
businessLocations[].businessStartDate | Start date of this business or location, if known. |
businessLocations[].businessEndDate | Closure or end date, if known. |
businessLocations[].operatingStatus | ACTIVE, CLOSED, TEMPORARILY_CLOSED, UNKNOWN, or null for this establishment. |
businessLocations[].industry | Industry or business activity associated with the location. |
businessLocations[].address | Structured address for this individual location: street number/name, city, postal code, region, and country. |
businessLocations[].address.streetNumber | House or building number for the location. |
businessLocations[].address.streetName | Street name for the location. |
businessLocations[].address.city | City where the location operates. |
businessLocations[].address.postalCode | Postal or ZIP code for the location. |
businessLocations[].address.region | State, province, or region for the location. |
businessLocations[].address.country | Country where the location operates. |
businessLocations[].contact | Contact details associated with the location: international/local phone and website. |
businessLocations[].contact.internationalPhone | Phone number in international dialing format. |
businessLocations[].contact.localPhone | Phone number in the local format used by the source. |
businessLocations[].contact.website | Official website URL for this location or business. |
businessLocations[].serviceAreas | Cities, districts, or other areas the business says it serves. |
| PREMIUM · Additional fields beyond Advance | |
financialProfile | Financial information from the latest identifiable public accounts. |
financialProfile.latestAccounts | Summary of the latest identifiable public financial accounts from one reporting period. |
financialProfile.latestAccounts.periodEnd | End date of the reporting period summarized. |
financialProfile.latestAccounts.currency | Currency used for the financial figures, preferably an ISO 4217 code. |
financialProfile.latestAccounts.revenue | Reported revenue for that period, or null if not publicly available. |
financialProfile.latestAccounts.operatingProfit | Reported operating profit for that period, when disclosed. |
financialProfile.latestAccounts.totalAssets | Reported total assets at the reporting date, when disclosed. |
financialProfile.latestAccounts.totalLiabilities | Reported total liabilities at the reporting date, when disclosed. |
financialProfile.latestAccounts.employeeCount | Employee count reported for that period, if available. |
businessLocations[].coordinates | Latitude and longitude as JSON numbers, or null when unavailable. |
businessLocations[].coordinates.latitude | North/south coordinate as a JSON number. |
businessLocations[].coordinates.longitude | East/west coordinate as a JSON number. |
businessLocations[].googleMaps | Google Maps identifiers for the matching location, when found. |
businessLocations[].googleMaps.placeId | Google Maps Place ID for the matching place. |
businessLocations[].googleMaps.cid | Google Maps customer identifier (CID) for the matching place. |
businessLocations[].marketplaceProfiles | Array of supported vehicle-marketplace profiles; each item identifies a platform, direct profile URL, and profile type. |
businessLocations[].marketplaceProfiles[].platformName | Name of the vehicle marketplace hosting the profile. |
businessLocations[].marketplaceProfiles[].profileUrl | Direct URL to the dealer profile, inventory, or relevant listing page. |
businessLocations[].marketplaceProfiles[].profileType | Type of marketplace page represented by the URL. |
Research result fields
The Premium download contains the complete research result. Regular and
Advance downloads are narrower projections: they do
not expose contractVersion, status, error,
companies, subjectMatch, fieldSources,
or the new per-location evidence fields. Choose Premium when your
integration needs these fields. A task with task.status=DONE
means a valid JSON result was stored; inspect its separate
result.status before treating the research as complete.
The raw research schema does not define a dedicated
telephoneVerification object or a
submittedEntity.providedDetails.telephone field. The API still
accepts an optional telephone input, but the Regular/Advance projection
may show null telephone-verification fields when the raw result contains
none. Check sourced businessLocations[].contact in Premium for
any telephone found for a location; do not interpret a null projection
as proof that the supplied number is wrong.
In the research result, null means a field was researched but no supported
value was found. An omitted optional field means that enrichment was not
researched. UNKNOWN means an allowed enum was researched but
the evidence is inconclusive. Do not interpret missing data or an unknown
status as a verified negative fact. Arrays contain only identified items;
no placeholder company or location is added to fill a template.
Result status and errors
| Field | Meaning |
|---|---|
contractVersion | Output contract identifier. Read this value before interpreting the remaining fields. |
status | COMPLETED means required identity, status, and evidence checks passed. PARTIAL means some research is usable but a required conclusion is unresolved. FAILED means the research did not yield a usable conclusion. This is inside the JSON and differs from the API task status. |
error.code | null for COMPLETED; otherwise one of EVIDENCE_INSUFFICIENT, SUBJECT_MATCH_UNRESOLVED, IDENTIFIER_UNVERIFIED, EVIDENCE_CONFLICT, RESEARCH_FAILED, SCHEMA_INVALID, or OTHER. |
error.message | null for COMPLETED; otherwise a nonempty explanation of what remains unresolved or failed. |
A syntactically valid PARTIAL or FAILED research
result can be stored under a DONE task. A worker or transport
failure instead makes the API task FAILED and the result
download unavailable. COMPLETED is reserved for a high-confidence
match to one returned item, verified company and site identifiers, specific
legal and operating statuses, direct field sources, and the required
research for the selected mode.
Companies and ownership
companies[] has one row per issuing-country and company-number
pair, even when several businessLocations[] rows belong to that
company. In France, these are company SIREN records; location numbers are
SIRETs. The top-level parentCompany remains for legacy output
compatibility. Use companies[i].parentCompany to associate a
parent with a particular company when the response contains several companies.
| Field | Meaning |
|---|---|
companies[].companyRegistrationNumber | Company registration identifier, such as a French SIREN; unique together with its issuing country. |
companies[].companyRegistrationCountryCode | Two-letter ISO country code for the authority that issued the company number. |
companies[].legalStatus | Company-level status: ACTIVE, CEASED, IN_LIQUIDATION, IN_RECEIVERSHIP, DORMANT, STRUCK_OFF, UNKNOWN, or null. It is distinct from a site's operating status. |
companies[].statusEffectiveDate | Date the supported legal status took effect, in YYYY-MM-DD format; null if unavailable. |
companies[].statusSourceId | sourceId of the source supporting the legal status; null if no source supports a specific status. |
companies[].parentCompany | Parent of this particular company; may be null after checking or omitted if not researched. A marketing network or brand is not proof of ownership. |
companies[].parentCompany.legalName | Legal name of the separately identified parent entity, when supported. |
companies[].parentCompany.companyRegistrationNumber | Parent's company number; it must differ from the operating company's number in the same issuing country. |
companies[].parentCompany.companyRegistrationCountryCode | Two-letter issuing-country code for the parent number; the parent may be registered abroad. |
companies[].parentCompany.relationshipType | PARENT for the direct parent, ULTIMATE_PARENT for the highest evidenced parent, or UNKNOWN when the relationship cannot be established. An unresearched or unsupported value may be null. |
companies[].parentCompany.ownershipPercent | Ownership percentage from an explicit source, from 0 to 100; null when no percentage is published. |
companies[].parentCompany.sourceId | ID of the source that proves the parent relationship, pointing into sources[]. |
Location identity and relocation
A location item represents one returned site or brand/channel candidate.
Two brand items may share the same SIRET while retaining distinct
locationKey values. The key is only stable within this one
response; persistent company and site identities remain their registration
numbers. Never infer a predecessor or successor SIRET from similar names,
addresses, closing dates, or opening dates.
| Field | Meaning |
|---|---|
businessLocations[].locationKey | Response-local item key: loc1, loc2, and so on in array order. Distinguishes brands sharing a site. |
businessLocations[].companyRegistrationCountryCode | Two-letter issuing-country code paired with this item's company number; together they identify one row in companies[]. |
businessLocations[].identifierVerified | true only if an official registry confirms this exact location number and its link to the stated company. Verifying only the caller's company number is insufficient. |
businessLocations[].identifierSource | OFFICIAL_REGISTRY when the location identifier is verified; otherwise null. |
businessLocations[].identifierSourceId | sourceId of that official registry record; otherwise null. |
businessLocations[].organizationType | HEADQUARTERS, BRANCH, SECONDARY_ESTABLISHMENT, UNKNOWN, or null for the establishment structure. |
businessLocations[].isRegisteredOffice | Whether this exact site is the legal registered office according to registry evidence; null when not established. |
businessLocations[].operatingStatus | ACTIVE, CLOSED, TEMPORARILY_CLOSED, UNKNOWN, or null for this site, independent of company legal status. |
businessLocations[].businessStartDate | Supported start date of this establishment, YYYY-MM-DD; it is not automatically the company's incorporation date. |
businessLocations[].businessEndDate | Supported end date of this establishment, if any; null for an ongoing or undated site. |
businessLocations[].relocation | Per-site SIRET lineage, distinct from submittedEntity.requestedLocationStatus.relocation, which describes the submitted address. Omitted if not researched; an object with null values means checked without a documented link. |
businessLocations[].relocation.previousLocationRegistrationNumber | Documented previous SIRET that this item replaced after a move to this site. |
businessLocations[].relocation.successorLocationRegistrationNumber | Documented successor SIRET that replaced this item after it moved away. |
businessLocations[].relocation.relocationDate | Registry-supported move date in YYYY-MM-DD format; null if unreported. |
Matching the submitted profile
There is one top-level subjectMatch for the entire response.
It identifies which returned item represents the submitted business
profile. A SIRET alone may identify a rooftop shared by several brands;
only matchedLocationKey identifies the exact item and channel.
The key, site number, and company number must agree with that item.
| Field | Meaning |
|---|---|
subjectMatch.matchedLocationKey | locationKey of the exact matching item; null if a brand/item cannot be distinguished. |
subjectMatch.matchedLocationRegistrationNumber | Matched site's registration number, such as a SIRET; null if only the company or no entity can be identified. |
subjectMatch.matchedCompanyRegistrationNumber | Matched operating company's registration number, such as a SIREN; null if unresolved. |
subjectMatch.matchBasis | Evidence types used: ADDRESS, PHONE, NAME, WEBSITE, GOOGLE_PLACE_ID, or INPUT_NUMBER. A similar name or supplied company number alone does not identify a site. |
subjectMatch.matchConfidence | HIGH for an exact item, MEDIUM for a site without a unique brand item, LOW for a company only, or NONE for no match. |
At HIGH, all three matched identifiers are present. At
MEDIUM, the item key is null while the site and company numbers
are known. At LOW, only the company number is known. At
NONE, all three identifiers are null and matchBasis
is empty. A high-confidence item match requires site or brand evidence
beyond NAME and INPUT_NUMBER.
Source classification and field evidence
| Field | Meaning |
|---|---|
sources[].sourceId | Unique response-local source key used by identifier, status, parent, and fieldSources references. |
sources[].sourceType | OFFICIAL_REGISTRY, COMMERCIAL_REGISTRY_AGGREGATOR, COMPANY_WEBSITE, MAPS, DIRECTORY, BUSINESS_PROFILE, NEWS, or OTHER. Pappers and similar aggregators are not official registries. |
sources[].registryAuthority | Issuer of an actual government registry, such as INSEE_SIRENE; null for every non-official source. |
sources[].supports | Concise plain-language facts supported by that source, without JSON paths. |
fieldSources | Top-level map from exact JSON field paths to nonempty arrays of supporting sourceId values. For example, "companies[0].legalStatus": ["s1"]. Indexes are zero-based, paths must exist and have meaningful values, and each source must directly support that field. |
For a COMPLETED result, direct field evidence is required for
the matched company's legal status, matched location's company and site
numbers and operating status, the registered-office flag when known, and
the matched site and company numbers in subjectMatch. Keep
statusSourceId and identifierSourceId consistent
with those mappings. An official source appearing somewhere in
sources[] does not automatically verify every field.
Responses and errors
- 201: new task batch accepted. 200: idempotent repeat returned the existing job.
- 202 from the result endpoint: task is still running;
retry after the response's
Retry-Afterdelay. - 409: task failed/cancelled, or the same idempotency key was reused with different input.
- 402: account balance is insufficient when billing is enabled.
- 403: the API key lacks a required business research API scope. 404: task does not exist or belongs to another account.
- 410: the completed result is no longer retained.
When billing is enabled, each entity is charged as one
REGULAR API task. The full JSON result is stored with the task
in MySQL and follows its one-year result retention period. Keep the
downloaded copy if you need it longer.
This API submits a business research request and returns its response; it does not guarantee that every business detail is present or independently verified. Review the returned JSON before using it for consequential decisions.