---
title: "Resolve target fields to registry-backed binding plans with evidence"
method: POST
path: "/v1/binding-resolutions"
tags: ["Bindings"]
---

# Resolve target fields to registry-backed binding plans with evidence

`POST /v1/binding-resolutions`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/binding-resolutions`
- Auth: HTTP bearer

Answers "which registry fields supply these target fields, and on what evidence" by climbing a cost ladder — memo, name retrieval, corpus mining, then optional LLM synthesis — and stopping at the first rung that meets `min_trust`. Read-mostly, on the `read` scope: plans proposed above the memo are written back as inert `candidate` rows so a tenant pays for a rung at most once, and nothing here activates, retires or verifies a plan. A target nothing could bind comes back with an empty `bindings` array — an abstention, never an omission.

## Request body

- BindingResolutionRequest
  - `targets` BindingResolutionTarget[], required
    - `field_key` string, required: The schema field to be filled.
    - `data_type` string
    - `description` string: What the field denotes. Read by the synthesis rung, which matches on meaning rather than name resemblance.
  - `allow_llm` boolean: Permit the ladder's LLM synthesis rung for targets nothing cheaper satisfied. Where the deployment has no LLM configured the ladder simply stops after corpus mining.
  - `min_trust` 'inferred' | 'mined' | 'verified': Grade that ends the climb. `inferred` = name identity only; `verified` = reproduced authored values it never saw.

## Response `200`

One entry per target, in the order given; each target's bindings ranked best first.

- object
  - `resolutions` BindingResolution[], required
    - `field_key` string, required
    - `bindings` BindingPlanBinding[], required: Ranked best first — verified-active plans, then by evidence lower bound. Empty when nothing could be bound.
      - `plan_id` string, uuid, nullable, required: The stored candidate plan. Null only for a plan not yet persisted.
      - `trust` 'inferred' | 'mined' | 'verified', required
      - `status` 'candidate' | 'active' | 'retired', required
      - `ladder` 'L0' | 'L1' | 'L2' | 'L3', required: Rung that produced the plan: memo, name retrieval, corpus mining, LLM synthesis.
      - `evidence` BindingPlanEvidence, required
        - `n` integer, required: Documents where the plan and an authored label were both present.
        - `agree` integer, required
        - `agreement` number, required: agree / n.
        - `ci95_low` number, required: Wilson lower bound at 95% — the number promotion gates compare against.
        - `distinct_values` integer, required: Distinct agreed values. One distinct value is close to no signal.
        - `method` 'mining' | 'synthesis' | 'human', required
        - `notes` string, nullable
      - `sources` BindingPlanSource[], required
        - `registry_id` string, uuid, required
        - `role` string, required: Plan-local handle the combine op refers to.
        - `canonical_name` string, nullable, required: Null when the registry entry no longer exists.
      - `combine` 'first_of' | 'template' | 'date_from_parts' | 'amount_currency' | 'null', nullable, required: How the source values become the target value.
      - `guard` BindingPlanGuard, required
        - `doc_type_id_in` string[], nullable, required
        - `doc_type_name_in` string[], nullable, required

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `422`: The request is well-formed but violates the declared task contract.
- `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)