Embed config sheets in your own tool

Mass configuration, kept in one place

A configurator, a quoting tool or an internal platform often depends on hundreds of small tables: the options each product range offers, the codes each supplier uses, the limits and parameters behind every variant. When those tables live in the application’s own database or in a folder of spreadsheets, every change is a release or a hand edit, and nobody can say which values were live last month.

With ConfigSheets behind your tool, the people who own the values maintain them as sheets with defined columns. Each change is checked and reviewed before it is saved, every saved version is kept, and your application reads the current version over the API.

• Option sets: the options, finishes and control sides each product range offers.
• Product configurations: the permitted combinations and limits for each variant, such as maximum widths per range and market.
• Code lists: customer, supplier and internal codes, kept as text so 0012 stays 0012.
• Parameter tables: the values your own rules read, such as allowances, lead-time bands or pack factors.

How a sheet is shaped

Each sheet has a type, such as BLIND_OPTIONS, a set of sheet-level parameters (key and value pairs such as the range and market it applies to) and its data: the rows, each a set of named fields. Your application asks for sheets by type, by parameter values and by values in their rows, and receives the matching sheets whole.

Integrating through GraphQL

Your application sends GraphQL queries to the ConfigSheets endpoint with a read credential in the Authorization header. The main query is configSheet, which takes one where argument of type ConfigSheetWhereInput and returns a list of ConfigSheet objects with name, params (a list of key and value pairs), data (the rows, as JSON) and updated_at.

Example. A blind configurator asks for the Roller 40 option sheet for the UK market, restricted to sheets that offer a left-hand control side. The sheet, codes and values below are synthetic.

query RollerOptionSheet($where: ConfigSheetWhereInput) {
  configSheet(where: $where) {
    name
    params {
      key
      value
    }
    data
    updated_at
  }
}

{
  "where": {
    "type": "BLIND_OPTIONS",
    "paramsFilters": [
      { "key": "range", "value": "Roller 40" },
      { "key": "market", "value": "UK" }
    ],
    "dataFilter": { "key": "control_side", "value": "LH" }
  }
}

{
  "data": {
    "configSheet": [
      {
        "name": "Roller 40 options (UK)",
        "params": [
          { "key": "range", "value": "Roller 40" },
          { "key": "market", "value": "UK" },
          { "key": "version", "value": "7" }
        ],
        "data": [
          { "option": "Chain, left hand", "control_side": "LH", "finish_code": "0012", "max_width_mm": 2400 },
          { "option": "Chain, right hand", "control_side": "RH", "finish_code": "0012", "max_width_mm": 2400 },
          { "option": "Motor, left hand", "control_side": "LH", "finish_code": "0031", "max_width_mm": 3000 }
        ],
        "updated_at": "2026-10-14 09:42:10"
      }
    ]
  }
}

dataFilter matches a sheet when any of its rows holds that value, and the response returns the whole sheet, so your application filters rows itself. Values keep their exact types: finish_code 0012 is text and stays 0012, while max_width_mm is a whole number.

Discovering what is available

Three smaller queries help a tool build its screens or check its mappings: configSheetTypes lists the sheet types in the workspace, and configSheetParamKeys and configSheetDataKeys list the parameter and row field names used by the sheets that match a where filter.

query DiscoverSheets {
  configSheetTypes
  configSheetParamKeys(where: { type: "BLIND_OPTIONS" })
  configSheetDataKeys(where: { type: "BLIND_OPTIONS" })
}

{
  "data": {
    "configSheetTypes": ["BLIND_OPTIONS", "PANEL_FINISHES"],
    "configSheetParamKeys": ["range", "market", "version"],
    "configSheetDataKeys": ["option", "control_side", "finish_code", "max_width_mm"]
  }
}

Combining conditions

ConfigSheetWhereInput combines conditions with AND, OR and NOT lists. paramsFilter and dataFilter each match one key and value; paramsFilters matches several parameters at once, and dataFilters matches several fields in the same row. This example selects UK or Irish panel finish sheets, leaving out any sheet with a row that pairs finish 0007 with Anthracite:

{
  "where": {
    "type": "PANEL_FINISHES",
    "OR": [
      { "paramsFilter": { "key": "market", "value": "UK" } },
      { "paramsFilter": { "key": "market", "value": "IE" } }
    ],
    "NOT": [
      { "dataFilters": [
        { "key": "finish_code", "value": "0007" },
        { "key": "colour", "value": "Anthracite" }
      ] }
    ]
  }
}

Versions and review, in integration terms

• Your application reads a reviewed, saved version. Drafts and changes awaiting review are never returned; a query returns the saved sheets as they stand.
• A change is reviewed before it becomes current. The review shows what is added, changed, removed and unchanged, with the values before and after. Until it is saved, your application keeps reading the previous version.
• A failed check changes nothing. A proposed change with a problem, such as a duplicate key or a code that would lose its leading zeros, leaves the saved version as it was.
• Every saved version is kept. Record the version your application used (in this example it is a sheet parameter) and you can show later exactly which values a quote or an order was built from.

One credential, one workspace

Every source, saved version, key and query belongs to the workspace the credential was issued for. The workspace comes from the verified credential, never from the request: no query takes a workspace or organisation argument, and a caller cannot widen its scope by naming another source in the request body.

Read credentials are issued by a workspace owner, shown once and stored only as a hash, expire, and can be revoked at any time. Reading and sending data in are separate abilities, so a credential that reads sheets cannot change them.

Screens inside your own tool

Your users do not have to leave your tool to change a value. The ConfigSheets editing and review screens can be embedded in your own interface or opened from it, so the people who own the values maintain and review them where they already work, with their own sign-in and roles. Your application, meanwhile, reads the result through the API.

Embedding ConfigSheets in your own tool is a paid integration: we scope it with you and agree the price before work starts. See how SmartFACT Data is offered.

Inside SmartFACT as well

The same sheets can also serve the SmartFACT suite: a saved version is delivered for review to LabelRules, KitProof, StoresFlow and the other products, each of which reviews and activates it on its own terms. One maintained table can feed your own tool and SmartFACT side by side. See Bringing your data into SmartFACT.

Read next

• Use casesWhere manufacturers use config sheets: customer codes on labels, supplier option codes, EDI, kit inputs, shop SKUs and configuration behind your own tool.
• Versioned reference tablesA versioned reference table keeps every saved version of a lookup table. See how SmartFACT Data checks each change, refuses stale edits and keeps every version.
• Data into SmartFACTFactory data reaches SmartFACT through each product’s own import or through SmartFACT Data. Which route suits which data, and how other systems are connected.