Create Resolution

Create a resolution run from a completed job with POST /v1/resolutions: freezes the normalization config into a snapshot and returns a pending run to execute.

Create a resolution run to normalize the field values extracted by a completed job run. Pass the job run's UUID as source_run_id; the platform verifies the run exists in your workspace and has reached completed status, then creates the resolution in pending state. Creation never starts processing on its own — call [POST /v1/resolutions/{id}/execute](execute-resolution) to start the pipeline.

Creation does two things beyond minting the run row. First, it freezes the schema's current normalization configuration into the run's policy_snapshot — the per-field reference tables, compute expressions, modifiers, format constraints — plus a dialect_snapshot when the schema has a dialect wired for delivery shaping. Second, it pre-creates one pending result row per document in the source run, so the run's document scope is fixed at creation time.

Because the configuration is snapshotted per run, resolutions are reproducible experiments: edit your reference data or field rules, create a fresh resolution against the same source_run_id, and compare results side by side. Earlier runs keep the configuration they were created with, and the source job's extracted values are never modified by any of them.

The source run must be a COMPLETED job run in your workspace. An unknown or foreign UUID returns 404; a run that exists but is still pending, processing, or failed returns 400 with "Source extraction run must be completed before creating a resolution run".

POST/v1/resolutions

Body parameters

source_run_id*uuidUUID of the completed job run whose extracted values will be resolved.

Request body

{
  "source_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

curl

curl -s -X POST https://api.talonic.com/v1/resolutions \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "source_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }'

Response

Response fields (201 Created)

idstringResolution run UUID.

source_run_idstringUUID of the originating job run.

statusstringAlways pending on creation.

policy_snapshotobjectThe normalization config frozen at creation: an auto-generated name, sanity_check flag, and the per-field rules.

dialect_snapshotobject | nullFrozen dialect configuration, or null when the schema has no dialect wired.

error_messagestring | nullAlways null on creation.

created_atstringISO 8601 creation timestamp.

updated_atstringISO 8601 timestamp, equal to created_at on creation.

linksobjectRelated resource URLs: self, results, source_run.

Response (201 Created)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "pending",
  "policy_snapshot": {
    "name": "Resolution 42Docs Jul 14",
    "sanity_check": false,
    "fields": [
      {
        "field_name": "country",
        "display_name": "Country",
        "data_type": "string",
        "reference_table": "iso-countries",
        "modifiers": null,
        "format": null,
        "suppress_output": false,
        "output_name": null
      }
    ]
  },
  "dialect_snapshot": null,
  "error_message": null,
  "created_at": "2026-07-14T10:32:00.000Z",
  "updated_at": "2026-07-14T10:32:00.000Z",
  "links": {
    "self": "/v1/resolutions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "results": "/v1/resolutions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/results",
    "source_run": "/v1/jobs/b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

The typical workflow is: create a job via POST /v1/jobs, poll it to completed, create a resolution with the job's run id, execute it, then poll [GET /v1/resolutions/{id}](get-resolution) and read the [results](get-resolution-results). The policy_snapshot.name is auto-generated from the document count and date (e.g. "Resolution 42Docs Jul 14"), with a Roman-numeral suffix appended when the same base name already exists — useful for telling repeated experiments apart in the list.

Errors

Error responses

400bad_requestInvalid request body, the source run is not completed yet, or a master-view API key was used (creates require a specific organization context).

401unauthorizedMissing or invalid API key.

404not_foundNo job run with this UUID exists in your organization.

429rate_limitedDaily request quota for your tier reached. The counter resets at midnight UTC.

Frequently asked questions

Do I need to call execute after creating a resolution?+

Yes. Creating a resolution only mints a pending run with a frozen configuration snapshot and one pending result row per source document. Nothing processes until you call POST /v1/resolutions/{id}/execute.

Can I create multiple resolutions from the same job run?+

Yes. Each resolution run freezes the normalization configuration current at ITS creation and produces its own results. This is the intended way to test rule or reference-data changes against the same extracted data — earlier runs keep the snapshot they were created with.

What happens if the source job run is not finished?+

A job run that exists but has not reached completed status is rejected with 400 ("Source extraction run must be completed before creating a resolution run"). An unknown UUID, or one belonging to another organization, returns 404. Wait for the job to complete, then create the resolution.

Which documents does the resolution cover?+

Exactly the documents that produced results in the source job run, fixed at creation time — one pending result row is pre-created per source document. Documents added to your workspace afterwards are not picked up; create a new job and a new resolution to cover them.