Ironclad API "record not found" when launching a workflow

Fix Ironclad "record not found" when launching a workflow via API

TL;DR

The workflow configuration ID in your launch call doesn't exist in the environment your API credential points at. Staging and production use different IDs, and a typo or a cached old ID produces the same error. List the workflow configurations through the API, copy the ID exactly, and confirm your credential targets the same environment the config lives in.

record not found

Steps

1. List workflow configurations via the API and find your workflow by name. Expected: a configuration ID in the response; compare it character for character with the ID in your launch call.

2. Confirm the environment: check which base URL and credential your call uses, and verify the config exists in that same environment (production vs staging/test). Expected: both sides agree; a mismatch here is the most common cause.

3. Check the configuration's state: it must be published, not archived or left in draft. Expected: status shows active/published; archived configs return the same "record not found".

4. Re-run the launch with the exact ID from step 1 against the matching environment. Expected: a success response with the new workflow record ID.

Use this when

• A workflow launch API call returns "record not found" but the workflow is visible in the UI
• You recently copied an integration from staging to production (or vice versa)
• The workflow was renamed, republished, or archived recently

Not for this skill when

• The error is "missing required field" (that's a payload problem, different skill)
• Your API credential itself is rejected (that's an auth problem)
• The workflow launches but gets stuck later (that's a routing/approval problem)

Variant phrasings

ironclad api workflow not found on launch

Same check: ID plus environment alignment.

ironclad launch workflow invalid configuration id

Usually a stale ID cached from an older version of the workflow.

ironclad record not found staging vs production

IDs don't carry across environments; fetch the ID from the environment you're calling.

Why it happens

Ironclad keeps environments separate, and workflow configuration IDs are environment-specific. The UI you look at may be production while your credential points at staging, or the config was archived and the ID silently stopped resolving. The API can't distinguish "wrong environment" from "deleted", so both surface as "record not found".

Edge cases

• Credentials can be scoped to a business unit or team that can't see the workflow even in the right environment.
• Republishing a workflow can mint a new configuration ID; re-fetch after any republish.
• Hardcoded IDs in env config drift over time; prefer looking the config up by name at deploy time.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstNO08vO6inS-EEVFWjheVA