Bankworks

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

  1. Sign in to the customer portal and create an API key.
  2. Set the key as the API_KEY environment 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.

Shell
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 fieldRequiredMeaningMaximum
modeNoregular, advance, or premium; controls result detailOne value per request
businessNameYesBusiness or group name500 characters
addressYesAddress, city, region, and/or postal code as supplied1,000 characters
countryYesCountry where the business is located200 characters
companyNumberNoProvided corporate ID or tax number; use null or omit it when unknown200 characters
telephoneNoProvided business telephone; AI Mode checks whether it is current and may return a verified replacement200 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.

Python
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)
Node.js
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);
}
cURL
: "${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.

JSON
{
  "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:

ModeFields returned in addition to the previous mode
RegularSubmitted identity and location status, business profile, source summaries, company-number and telephone verification, and data quality.
AdvanceEverything in Regular, plus a parent-company summary, ownership and control, and business-location summaries with addresses and contacts.
PremiumThe complete raw result: outcome status/error, distinct companies[], exact subjectMatch, per-field fieldSources, financial data, and detailed location identifiers, relocation, maps, and marketplace profiles.
JSON
{
  "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"
  }
}
JSON
{
  "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"
  }
}
JSON
{
  "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"
  }
}
JSON REFERENCE

Field meanings

Each tab shows only the fields added by that mode compared with the previous one.

Regular · Advance · Premium
FieldMeaning
REGULAR · Core fields
submittedEntityThe business and location submitted for research, with the result for that requested location.
submittedEntity.providedDetailsThe original input values, preserved so the result can be matched to the submitted entity.
submittedEntity.providedDetails.businessNameBusiness or group name as supplied by the caller.
submittedEntity.providedDetails.streetStreet portion of the supplied address, when it can be separated.
submittedEntity.providedDetails.postalCodePostal or ZIP code from the supplied address, when available.
submittedEntity.providedDetails.cityCity from the supplied address, when available.
submittedEntity.providedDetails.countryCountry supplied for the business.
submittedEntity.providedDetails.companyNumberCorporate or tax number supplied by the caller; null when none was provided.
submittedEntity.providedDetails.telephoneCaller-supplied phone when the underlying research result includes it; otherwise the Regular/Advance projection uses null.
submittedEntity.requestedLocationStatusRegistry status and any relocation information for the exact submitted location.
submittedEntity.requestedLocationStatus.statusACTIVE, CLOSED, MOVED, or UNKNOWN for the requested location.
submittedEntity.requestedLocationStatus.registryActionRelevant registry action or event behind the status, when supported by evidence.
submittedEntity.requestedLocationStatus.statusEffectiveDateDate the status or registry action took effect, formatted as YYYY-MM-DD.
submittedEntity.requestedLocationStatus.relocationRelocation details when the requested location is marked MOVED; otherwise null.
submittedEntity.requestedLocationStatus.relocation.movedWithinSameCountryWhether evidence indicates the business moved within the same country.
submittedEntity.requestedLocationStatus.relocation.newAddressStructured destination address after a move.
submittedEntity.requestedLocationStatus.relocation.newAddress.streetNumberHouse or building number at the new address.
submittedEntity.requestedLocationStatus.relocation.newAddress.streetNameStreet name at the new address.
submittedEntity.requestedLocationStatus.relocation.newAddress.cityCity at the new address.
submittedEntity.requestedLocationStatus.relocation.newAddress.postalCodePostal or ZIP code at the new address.
submittedEntity.requestedLocationStatus.relocation.newAddress.regionState, province, or region at the new address.
submittedEntity.requestedLocationStatus.relocation.newAddress.countryCountry at the new address.
companyNumberVerificationComparison of the submitted company number with the resolved entity and registry evidence.
companyNumberVerification.providedCompanyNumberCompany number supplied by the caller.
companyNumberVerification.verificationStatusVALID, INVALID_OR_NOT_FOUND, NOT_PROVIDED, or UNKNOWN.
companyNumberVerification.resolvedCompanyNumberOfficial number resolved for the matching company, if available.
companyNumberVerification.resolutionNotesShort explanation of the number match, mismatch, or resolution.
telephoneVerificationProjected phone-verification fields. They may all be null because the raw result does not define this object.
telephoneVerification.providedTelephoneCaller-supplied telephone if the underlying result preserved it; otherwise null.
telephoneVerification.verificationStatusVALID, INVALID_OR_OUTDATED, UNVERIFIABLE, or NOT_PROVIDED.
telephoneVerification.resolvedTelephoneCurrent business telephone confirmed by reliable public evidence, if available.
telephoneVerification.resolutionNotesShort evidence-based explanation of the match, mismatch, or inability to verify.
businessProfileConcise customer-facing description of the business and its activity.
businessProfile.descriptionFactual summary of what the business does.
businessProfile.productsAndServicesProducts and services supported by the sources.
businessProfile.industryCodesIndustry classification codes with their system, code, and label.
businessProfile.industryCodes[].systemClassification system used for the industry code.
businessProfile.industryCodes[].codeCode assigned by that classification system.
businessProfile.industryCodes[].labelReadable industry description for the code.
sourcesSources actually consulted to support the result, shared by every mode.
sources[].sourceNameName of the registry, website, profile, or publication consulted.
sources[].sourceTypeSource category: official registry, commercial aggregator, company website, maps, directory, business profile, news, or other.
sources[].sourceUrlExact HTTP(S) page URL when available; otherwise null. The worker converts non-URL source references to null.
sources[].accessedAtUTC timestamp when the source was checked.
sources[].supportsPlain-language facts supported by this source; JSON paths belong in fieldSources.
dataQualitySummary of how complete and consistent the evidence is for this result.
dataQuality.confidenceLevelHIGH, MEDIUM, LOW, or UNKNOWN for overall evidence strength.
dataQuality.confidenceScoreEvidence-based integer from 0 to 100; it is not a statistically measured probability.
dataQuality.assessmentReasonExplanation of the evidence and any uncertainty behind the quality assessment.
dataQuality.checkedAtUTC timestamp when this research result was assembled.
ADVANCE · Additional fields beyond Regular
parentCompanyTop-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.legalNameParent company's legal name.
parentCompany.companyRegistrationNumberParent company's official registration number.
parentCompany.currentSiteStatusCurrent status of the parent company's site: ACTIVE, CLOSED, MOVED, or UNKNOWN.
ownershipAndControlPublicly supported beneficial ownership and director information.
ownershipAndControl.beneficialOwnersPeople publicly identified as owning or controlling the entity.
ownershipAndControl.beneficialOwners[].namePublicly listed beneficial owner name.
ownershipAndControl.beneficialOwners[].ownershipPercentOwnership percentage when explicitly stated by a reliable source; otherwise null.
ownershipAndControl.beneficialOwners[].controlTypeEvidence-based description of how the person owns or controls the entity.
ownershipAndControl.directorsPublicly listed directors or equivalent company officers.
ownershipAndControl.directors[].namePublicly listed director or officer name.
ownershipAndControl.directors[].roleRole held by that person in the company.
ownershipAndControl.directors[].appointedDateAppointment date when available.
ownershipAndControl.directors[].resignedDateResignation date when available; otherwise null.
businessLocationsArray of returned sites or brand items, including relevant branches or other companies when supported; may be empty or contain multiple entries.
businessLocations[].brandOrDepartmentNameBrand or department name associated with this location.
businessLocations[].publicNameName used publicly by this business location.
businessLocations[].companyRegistrationNumberRegistration number of the company operating this location.
businessLocations[].locationRegistrationNumberRegistration identifier specific to the branch or location.
businessLocations[].vatNumberVAT registration number for this business, when available.
businessLocations[].franchiseTypeFRANCHISE or INDEPENDENT when evidence supports a classification.
businessLocations[].organizationTypeHEADQUARTERS, BRANCH, SECONDARY_ESTABLISHMENT, UNKNOWN, or null; this classifies the establishment, not its legal company form.
businessLocations[].parentCompanyNameName of the parent company associated with this location.
businessLocations[].networkNameDealer group, franchise network, or other business network name.
businessLocations[].businessStartDateStart date of this business or location, if known.
businessLocations[].businessEndDateClosure or end date, if known.
businessLocations[].operatingStatusACTIVE, CLOSED, TEMPORARILY_CLOSED, UNKNOWN, or null for this establishment.
businessLocations[].industryIndustry or business activity associated with the location.
businessLocations[].addressStructured address for this individual location: street number/name, city, postal code, region, and country.
businessLocations[].address.streetNumberHouse or building number for the location.
businessLocations[].address.streetNameStreet name for the location.
businessLocations[].address.cityCity where the location operates.
businessLocations[].address.postalCodePostal or ZIP code for the location.
businessLocations[].address.regionState, province, or region for the location.
businessLocations[].address.countryCountry where the location operates.
businessLocations[].contactContact details associated with the location: international/local phone and website.
businessLocations[].contact.internationalPhonePhone number in international dialing format.
businessLocations[].contact.localPhonePhone number in the local format used by the source.
businessLocations[].contact.websiteOfficial website URL for this location or business.
businessLocations[].serviceAreasCities, districts, or other areas the business says it serves.
PREMIUM · Additional fields beyond Advance
financialProfileFinancial information from the latest identifiable public accounts.
financialProfile.latestAccountsSummary of the latest identifiable public financial accounts from one reporting period.
financialProfile.latestAccounts.periodEndEnd date of the reporting period summarized.
financialProfile.latestAccounts.currencyCurrency used for the financial figures, preferably an ISO 4217 code.
financialProfile.latestAccounts.revenueReported revenue for that period, or null if not publicly available.
financialProfile.latestAccounts.operatingProfitReported operating profit for that period, when disclosed.
financialProfile.latestAccounts.totalAssetsReported total assets at the reporting date, when disclosed.
financialProfile.latestAccounts.totalLiabilitiesReported total liabilities at the reporting date, when disclosed.
financialProfile.latestAccounts.employeeCountEmployee count reported for that period, if available.
businessLocations[].coordinatesLatitude and longitude as JSON numbers, or null when unavailable.
businessLocations[].coordinates.latitudeNorth/south coordinate as a JSON number.
businessLocations[].coordinates.longitudeEast/west coordinate as a JSON number.
businessLocations[].googleMapsGoogle Maps identifiers for the matching location, when found.
businessLocations[].googleMaps.placeIdGoogle Maps Place ID for the matching place.
businessLocations[].googleMaps.cidGoogle Maps customer identifier (CID) for the matching place.
businessLocations[].marketplaceProfilesArray of supported vehicle-marketplace profiles; each item identifies a platform, direct profile URL, and profile type.
businessLocations[].marketplaceProfiles[].platformNameName of the vehicle marketplace hosting the profile.
businessLocations[].marketplaceProfiles[].profileUrlDirect URL to the dealer profile, inventory, or relevant listing page.
businessLocations[].marketplaceProfiles[].profileTypeType 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

FieldMeaning
contractVersionOutput contract identifier. Read this value before interpreting the remaining fields.
statusCOMPLETED 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.codenull for COMPLETED; otherwise one of EVIDENCE_INSUFFICIENT, SUBJECT_MATCH_UNRESOLVED, IDENTIFIER_UNVERIFIED, EVIDENCE_CONFLICT, RESEARCH_FAILED, SCHEMA_INVALID, or OTHER.
error.messagenull 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.

FieldMeaning
companies[].companyRegistrationNumberCompany registration identifier, such as a French SIREN; unique together with its issuing country.
companies[].companyRegistrationCountryCodeTwo-letter ISO country code for the authority that issued the company number.
companies[].legalStatusCompany-level status: ACTIVE, CEASED, IN_LIQUIDATION, IN_RECEIVERSHIP, DORMANT, STRUCK_OFF, UNKNOWN, or null. It is distinct from a site's operating status.
companies[].statusEffectiveDateDate the supported legal status took effect, in YYYY-MM-DD format; null if unavailable.
companies[].statusSourceIdsourceId of the source supporting the legal status; null if no source supports a specific status.
companies[].parentCompanyParent 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.legalNameLegal name of the separately identified parent entity, when supported.
companies[].parentCompany.companyRegistrationNumberParent's company number; it must differ from the operating company's number in the same issuing country.
companies[].parentCompany.companyRegistrationCountryCodeTwo-letter issuing-country code for the parent number; the parent may be registered abroad.
companies[].parentCompany.relationshipTypePARENT 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.ownershipPercentOwnership percentage from an explicit source, from 0 to 100; null when no percentage is published.
companies[].parentCompany.sourceIdID 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.

FieldMeaning
businessLocations[].locationKeyResponse-local item key: loc1, loc2, and so on in array order. Distinguishes brands sharing a site.
businessLocations[].companyRegistrationCountryCodeTwo-letter issuing-country code paired with this item's company number; together they identify one row in companies[].
businessLocations[].identifierVerifiedtrue 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[].identifierSourceOFFICIAL_REGISTRY when the location identifier is verified; otherwise null.
businessLocations[].identifierSourceIdsourceId of that official registry record; otherwise null.
businessLocations[].organizationTypeHEADQUARTERS, BRANCH, SECONDARY_ESTABLISHMENT, UNKNOWN, or null for the establishment structure.
businessLocations[].isRegisteredOfficeWhether this exact site is the legal registered office according to registry evidence; null when not established.
businessLocations[].operatingStatusACTIVE, CLOSED, TEMPORARILY_CLOSED, UNKNOWN, or null for this site, independent of company legal status.
businessLocations[].businessStartDateSupported start date of this establishment, YYYY-MM-DD; it is not automatically the company's incorporation date.
businessLocations[].businessEndDateSupported end date of this establishment, if any; null for an ongoing or undated site.
businessLocations[].relocationPer-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.previousLocationRegistrationNumberDocumented previous SIRET that this item replaced after a move to this site.
businessLocations[].relocation.successorLocationRegistrationNumberDocumented successor SIRET that replaced this item after it moved away.
businessLocations[].relocation.relocationDateRegistry-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.

FieldMeaning
subjectMatch.matchedLocationKeylocationKey of the exact matching item; null if a brand/item cannot be distinguished.
subjectMatch.matchedLocationRegistrationNumberMatched site's registration number, such as a SIRET; null if only the company or no entity can be identified.
subjectMatch.matchedCompanyRegistrationNumberMatched operating company's registration number, such as a SIREN; null if unresolved.
subjectMatch.matchBasisEvidence 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.matchConfidenceHIGH 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

FieldMeaning
sources[].sourceIdUnique response-local source key used by identifier, status, parent, and fieldSources references.
sources[].sourceTypeOFFICIAL_REGISTRY, COMMERCIAL_REGISTRY_AGGREGATOR, COMPANY_WEBSITE, MAPS, DIRECTORY, BUSINESS_PROFILE, NEWS, or OTHER. Pappers and similar aggregators are not official registries.
sources[].registryAuthorityIssuer of an actual government registry, such as INSEE_SIRENE; null for every non-official source.
sources[].supportsConcise plain-language facts supported by that source, without JSON paths.
fieldSourcesTop-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

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.