Skip to content

Lookup business partners

Tool name: reference_data-lookup_business_partners

When: the user wants to find candidate business partners by any combination of company name, address parts and identifiers (VAT, PL_REG, etc.) — including by an identifier alone.

What it returns: a paginated list of slim matches. Each match carries:

  • cdqId, local-language name, a composed address string and external id
  • identifiers (VAT, PL_REG, ...) as {value, type} pairs
  • status and source-of-record identity (technicalKey + name)
  • a matching score

It may also return warnings: notices the search made about itself, each with a severity and a plain-language message, most often saying that some of the data the search was asked to cover is not enabled for the caller's organization. A warning qualifies the result and never means the search failed — relay it to the user when it explains a short or empty list of matches, along with whatever its message asks them to do.

What it does not do:

  • It does not query Dun & Bradstreet or Bureau van Dijk, so it cannot answer a request for a DUNS number or a BvD ID.
  • It does not return full business partner details (no bank accounts, relations, classifications, raw SAP record, etc.), only the slim matches above.

Input schema

companyNamestring

The legal or trading name of the company to look up, e.g. "REFRIGERACAO DUFRIO COMERCIAL LTDA".

countryCodestring

ISO 3166-1 alpha-2 country code, e.g. "PL".

streetstring

Street address (street name plus number if known), e.g. "al. Jana Pawła II 6".

citystring

City name, e.g. "Jawor".

postCodestring

Postal code, e.g. "59-400".

identifiersArray of objects(IdentifierParam)

Identifying numbers (VAT, PL_REG, DUNS, etc.), e.g. [{"value":"1234567890","type":"PL_NIP"}].

dataSourcesArray of strings

Restrict the search to specific data sources, given as ALEI prefixes, e.g. ["BR.RF"] or ["PL.NOBR","BR.RF"]. An ALEI prefix is the part of a cdqId before the colon: a match with cdqId "BR.RF:01754239004298" comes from the "BR.RF" data source, so a prefix can be read off any earlier result. Omit this to search every data source the caller can access.

startAfterstring

Pagination cursor. Omit for the first page; pass the nextStartAfter value from the previous result to fetch the next page.

limitinteger, (int32), [ 1 .. 50 ]

Items per page, e.g. 5. Allowed range 1..50; defaults to 5 to keep response tokens small.

Default:5
Input example
{}

Output schema

matchesArray of objects(BusinessPartnerLookupMatch)
limitinteger
totalMatchesinteger
nextStartAfterstring

Cursor for the next page; pass it as startAfter.

warningsArray of objects or null(LookupWarning)
Output example
{}