Advanced Search

The advanced search API queries your third parties, dossiers and documents using a criteria builder: a tree of conditions you compose freely, over any field available for your account.

One sentence, one query

Let’s take a business need expressed in plain language, and see how it translates into a query.

{
  "filters": {
    "connectiveOperator": "AND",
    "conditions": [
      {
        "field": {
          "field": "<indicatorId>",
          "fieldType": "TEXT",
          "nature": "INDICATOR",
          "resourceType": "THIRD_PARTY",
          "id": <indicatorId>
        },
        "operator": "EQUAL",
        "values": ["High Risk"]
      },
      {
        "field": {
          "field": "documentTypeId",
          "fieldType": "TEXT",
          "nature": "MAIN_FIELD",
          "resourceType": "DOCUMENT"
        },
        "operator": "EQUAL",
        "values": [4311]
      },
      {
        "field": {
          "field": "documentStatus",
          "fieldType": "TEXT",
          "nature": "MAIN_FIELD",
          "resourceType": "DOCUMENT"
        },
        "operator": "EQUAL",
        "values": ["MISSING"]
      }
    ],
    "childGroups": []
  },
  "sort": { "name": "ASC" }
}

The three conditions are joined by AND: only third parties matching all three are returned.

Three queryable resources

The same mechanism applies to three resources. A condition can even target a resource other than the one queried (cross-resource filtering) — for example finding third parties that have a dossier of a given type.

The principle: a tree of conditions

A group has a single operator (AND or OR) that joins all its conditions and sub-groups. To mix AND and OR, you nest sub-groups — depth is unlimited.

Example: A AND (B OR C) is modeled as an AND group containing condition A and an OR sub-group containing B and C.

The 3-step flow

From catalog to query

In practice: you fetch a field from the reference-data catalog, then copy its descriptor into a search condition.

{
  "field": "addressCountryCode",
  "label": "Pays",
  "fieldType": "TEXT",
  "nature": "MAIN_FIELD",
  "resourceType": "THIRD_PARTY",
  "options": [ { "value": "FR", "label": "France" }, … ],
  "availableOperators": ["EQUAL", "IN_SET", …]
}

{
  "field": {
    "field": "addressCountryCode",
    "fieldType": "TEXT",
    "nature": "MAIN_FIELD",
    "resourceType": "THIRD_PARTY"
  },
  "operator": "EQUAL",
  "values": ["FR"]
}

The highlighted fields come from the catalog; the operator and values are up to you.

Anatomy of a condition

A condition combines a field, an operator and values.

{
  "field": {
    "field": "addressCountryCode",
    "fieldType": "TEXT",
    "nature": "MAIN_FIELD",
    "resourceType": "THIRD_PARTY"
  },
  "operator": "EQUAL",
  "values": ["FR"]
}

Field natures

Each field carries a nature indicating where the data comes from. For attributes, calculated attributes, indicators and form fields, an identifier (id) is required.

The endpoints

Each resource exposes a search endpoint (and its export twin).

Export

Each resource has an export endpoint, the twin of the search: same request body (filters, sort, outputs), but it returns a file (CSV, XLS or XLSX) instead of paginated JSON. The endpoint is the search URL suffixed with /export, and the format is chosen via the required exportType parameter.

Choosing columns

The body additionally accepts columnsVisibility, which maps each column code to true or false and works as an opt-out: by default all columns are exported, you only list those to hide (false). A column set to true or absent stays visible — so omitting columnsVisibility exports everything.

Example — export third parties without the DUNS and VAT columns:

{ "columnsVisibility": { "duns": false, "vat": false } }

This page covers the concepts. The full list of fields, operators and possible values is provided dynamically by the reference-data catalog, specific to your account.