Skip to main content

Get Package Config

Retrieve a single matching package config by ID: document-type slots, presence rules, pass criteria, and a link to the config's run history. Tenant-scoped.

Retrieve a single matching package config by its UUID. The response is the full config: its name, the document-type slots with their matching config IDs and presence rules, the pass criteria, and resource links. The config must belong to your organization.

Use this endpoint to inspect a config before triggering a run, to confirm the document types and presence rules are what you expect, or to hydrate a config editor. The links.runs URL points at the run list filtered to this config so you can jump straight to its run history.

Lookups are tenant-scoped. A config that does not exist, or that belongs to another organization, returns 404 not_found rather than leaking its existence. Pass the id exactly as returned by the create or list endpoints — it must be a UUID, and a malformed id is rejected with a 400 before any lookup happens.

Because the public API has no update endpoint for package configs, the shape you read here is immutable: the config a run scored against is exactly the config as created. To change slots or pass criteria, create a new config and point future runs at its id — old runs keep referencing the config they actually used, which keeps run history honest.

GET/v1/matching/packages/configs/{id}

Path parameters

id*stringUUID of the package config. Must belong to your organization.

curl

curl -s https://api.talonic.com/v1/matching/packages/configs/4f2a9c1e-8b3d-47e6-9a05-c7d1e2f3a4b5 \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

idstringPackage config UUID.
namestringPackage config name.
document_type_configsarrayDocument-type slots with matching_config_id and presence.
pass_criteriaobjectPass/fail aggregation rules.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last-update timestamp.
links.selfstringURL of this config.
links.runsstringURL listing runs for this config.

Response

{
  "id": "4f2a9c1e-8b3d-47e6-9a05-c7d1e2f3a4b5",
  "name": "Shipment bundle",
  "document_type_configs": [
    { "document_type": "invoice", "matching_config_id": "1a2b3c4d-5e6f-4781-92a3-b4c5d6e7f809", "presence": "required" },
    { "document_type": "delivery_note", "matching_config_id": "2b3c4d5e-6f70-4192-a3b4-c5d6e7f8091a", "presence": "expected" },
    { "document_type": "contract", "matching_config_id": "3c4d5e6f-7081-42a3-b4c5-d6e7f8091a2b", "presence": "optional" }
  ],
  "pass_criteria": {
    "all_required_matched": true,
    "min_confidence": 0.8,
    "allow_review_on_expected": true
  },
  "created_at": "2024-09-14T10:32:00.000Z",
  "updated_at": "2024-09-14T10:32:00.000Z",
  "links": {
    "self": "/v1/matching/packages/configs/4f2a9c1e-8b3d-47e6-9a05-c7d1e2f3a4b5",
    "runs": "/v1/matching/packages/runs?package_config_id=4f2a9c1e-8b3d-47e6-9a05-c7d1e2f3a4b5"
  }
}
Check a config with this endpoint before triggering a run: the document_type values in its slots are exactly the keys your input_documents map must use, so a mismatch here is the most common cause of skipped slots.

Errors

Error responses

400validation_errorInvalid config ID format. Must be a UUID.
401unauthorizedMissing or invalid API key.
404not_foundNo package config with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What does the links.runs URL return?+
It points at the package runs list filtered to this config, so you can retrieve the full run history for the config in one call.
Why do I get a 404 for a config I know exists?+
The config belongs to a different organization. Configs are tenant-scoped, so one tenant cannot read another tenant's configs, even with a valid ID. A 400 instead of a 404 means the id is not a well-formed UUID at all.
Why should I read the config before triggering a run?+
Because the slots' document_type values are the exact keys your run's input_documents map must use — a key that matches no slot is simply not scored, and a slot with no matching key counts as a missing document. Reading the config first is the cheapest way to avoid a silently skipped type.
Can I update a package config after creating it?+
The public API exposes create, read, and delete for package configs, but no update endpoint. To change slots or pass criteria, create a new config with the revised settings and point your runs at its ID.

Related

List Package Configs
Delete Package Config