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 matching configurations. Each table stores rows of structured data that documents are compared against during matching runs. 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 or the file upload endpoint.

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.

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

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.

Get Reference Data

Reference Data Rows & Export

Create Matching Config

List & Create

Response (GET)

Create Reference Data

Response (POST)

Errors

Related