---
title: "Create a matching configuration"
method: POST
path: "/v1/matching/configs"
tags: ["Matching"]
---

# Create a matching configuration

`POST /v1/matching/configs`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/matching/configs`
- Auth: HTTP bearer

Link a reference dataset to a target scope via weighted field mappings.
The reference dataset must belong to the authenticated customer.

## Request body

- MatchingConfigCreateRequest
  - `name` string, required: Human-readable configuration name.
  - `reference_data_id` string, uuid, required: UUID of the reference dataset to match against.
  - `field_mappings` MatchingFieldMapping[], required: Weighted field-mapping entries. Must be non-empty.
    - `extracted_field` string: Name or id of the extracted field.
    - `reference_column` string: Reference dataset column to match against.
    - `match_type` 'exact' | 'fuzzy' | 'date_range' | 'numeric_range': Matching strategy applied to this pair.
    - `weight` number, float: Relative weight used to aggregate the final confidence.
  - `threshold` number, float: Auto-accept confidence threshold (defaults to 0.85 server-side).
  - `target_type` 'run' | 'schema' | 'document_filter': Target scope type (defaults to `run`).
  - `target_value` object: Free-form target identifier payload (e.g. `{ run_id }`).

## Response `200`

Matching configuration created (alias of 201).

- MatchingConfigResponse
  - `id` string, uuid, required
  - `name` string, required
  - `reference_data_id` string, uuid, required
  - `target_type` 'run' | 'schema' | 'document_filter'
  - `target_value` object: Target identifier payload (e.g. run_id, schema_id).
  - `field_mappings` MatchingFieldMapping[], required
    - `extracted_field` string: Name or id of the extracted field.
    - `reference_column` string: Reference dataset column to match against.
    - `match_type` 'exact' | 'fuzzy' | 'date_range' | 'numeric_range': Matching strategy applied to this pair.
    - `weight` number, float: Relative weight used to aggregate the final confidence.
  - `threshold` number, float, required: Auto-accept confidence threshold.
  - `created_at` string, date-time
  - `updated_at` string, date-time, nullable
  - `links` object
    - `self` string
    - `runs` string

## Other responses

- `201`: Matching configuration created.
- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `404`: The requested resource was not found.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)