Skip to main content

List & Create

List all reference data tables in your workspace or create a new one from a JSON payload. Reference data tables store lookup datasets used as matching targets.

Reference data tables are uploaded datasets (CSV, XLSX, or JSON) that serve as lookup targets for the Matching family of operations. Each table stores rows of structured data that documents are compared against during Matching runs — whether a plain match that ranks candidate rows, or Reconciliation, the Matching mode that verifies extracted values against an authoritative dataset. Use this endpoint to list all reference data tables in your workspace, or create a new table from a JSON payload.

Each table in the response includes its column schema (derived automatically from the data), row count, and HATEOAS links to the table detail and rows endpoints. Tables are workspace-scoped — you will only see tables created within your authenticated workspace.

Creating a reference data table from JSON is the fastest path for programmatic workflows. The column schema is derived automatically from the keys and value types of the first row in the data array. All subsequent rows are validated against this derived schema. For CSV or XLSX uploads, use the platform UI upload flow.

A typical workflow is: create a reference data table via POST /v1/reference-data, note the returned id, then create a matching config via POST /v1/matching/configs with reference_data_id set to that ID. The matching config defines how document fields map to reference data columns.

Column schemas are derived automatically from the first row of your data. Ensure the first row contains representative values for all columns — missing keys in the first row will not appear in the schema.
  • Tables are workspace-scoped and isolated by tenant.
  • Column schemas are inferred from the first row of the JSON payload.
  • Each table tracks its row_count and columns metadata.
  • Use the links.rows URL to paginate through the table contents.
GET/v1/reference-data

Response (GET)

Response fields

dataarrayArray of reference data table objects.
data[].idstringReference data table UUID.
data[].namestringHuman-readable table name.
data[].source_typestringHow the table was created (e.g. "json", "csv", "xlsx").
data[].row_countintegerNumber of rows in the table.
data[].columnsarrayArray of column definitions with name and inferred type.
data[].created_atstringISO 8601 creation timestamp.
data[].links.selfstringURL to this table.
data[].links.rowsstringURL to paginate through the table rows.

cURL — List tables

Response

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Vendor Master List",
      "source_type": "csv",
      "row_count": 1250,
      "columns": [
        { "name": "vendor_id", "type": "string" },
        { "name": "vendor_name", "type": "string" },
        { "name": "country", "type": "string" },
        { "name": "tax_id", "type": "string" }
      ],
      "created_at": "2024-09-15T10:00:00.000Z",
      "links": {
        "self": "/v1/reference-data/b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "rows": "/v1/reference-data/b2c3d4e5-f6a7-8901-bcde-f12345678901/rows"
      }
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Product Catalogue",
      "source_type": "json",
      "row_count": 430,
      "columns": [
        { "name": "sku", "type": "string" },
        { "name": "description", "type": "string" },
        { "name": "unit_price", "type": "number" }
      ],
      "created_at": "2024-10-01T08:30:00.000Z",
      "links": {
        "self": "/v1/reference-data/c3d4e5f6-a7b8-9012-cdef-123456789012",
        "rows": "/v1/reference-data/c3d4e5f6-a7b8-9012-cdef-123456789012/rows"
      }
    }
  ]
}

Create Reference Data

Create a new reference data table by sending a JSON payload with a name and an array of row objects. The column schema is derived from the keys and value types of the first object in the data array. Subsequent rows are stored as-is. This endpoint is the primary programmatic path for populating reference data — for CSV or XLSX files, use the platform UI upload flow.

POST/v1/reference-data

Body parameters

name*stringHuman-readable name for the reference data table.
data*arrayArray of row objects. The first row defines the column schema.
columnsstring[]Optional explicit column order. When omitted, column order is derived from the first row.

Response (POST)

Response fields (201 Created)

idstringReference data table UUID.
namestringTable name.
source_typestringAlways "json" for API-created tables.
row_countintegerNumber of rows stored.
columnsarrayDerived column definitions.
created_atstringISO 8601 creation timestamp.
links.selfstringURL to this table.
links.rowsstringURL to paginate through the table rows.

cURL — Create table

Response (201 Created)

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "name": "Vendor Master List",
  "source_type": "json",
  "row_count": 3,
  "columns": [
    { "name": "vendor_id", "type": "string" },
    { "name": "vendor_name", "type": "string" },
    { "name": "country", "type": "string" },
    { "name": "tax_id", "type": "string" }
  ],
  "created_at": "2024-09-15T10:00:00.000Z",
  "links": {
    "self": "/v1/reference-data/b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "rows": "/v1/reference-data/b2c3d4e5-f6a7-8901-bcde-f12345678901/rows"
  }
}

Errors

Error responses

400validation_errorMissing required fields (name, data) or empty data array.
401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Get Reference Data
Reference Data Rows & Export
Create Matching Config
Analyze Reference Data for Reconciliation (a Matching mode)