Unlock form

Form URLs expire after 31 days and will no longer be accessible. Use this endpoint to restore access to an expired or locked form, or to generate a form for a verification that was not originally created through the Forms API.

In the test environment, forms expire after 20 minutes instead of 31 days.

POST/v5/forms/:trace/unlock

Unlock a form

If the form already exists, this endpoint resets the form, allowing the user to access, edit, and resubmit. This works for forms that have not yet been submitted, as well as forms where the verification has been processed and is in info status. If the verification has already reached a final status (e.g. verified), the form cannot be unlocked.

If no form exists for the given trace but the verification is in info status, a new form will be created automatically using the existing verification data. This is useful when the original verification was submitted via the API or the Portal rather than through a form.

Path parameters

Name
trace
Type
string
Description
The unique identifier (trace) for the verification.

Error responses

Status	Type	Description
`404`	`not_found`	The trace was not found or does not belong to your account.
`422`	`validation_error`	The verification status is not `info`.

Request

POST

/v5/forms/:trace/unlock

curl -X POST https://dev.bronid.com/v5/forms/1LuRUfAcaskosWc07nARZ/unlock \
  --user "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2:api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314"

Response

{
  "timestamp": "2026-01-27T04:34:37.668Z",
  "serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "trace": "1LuRUfAcaskosWc07nARZ",
  "path": "/v5/forms/1LuRUfAcaskosWc07nARZ/unlock",
  "pathParams": {
    "trace": "1LuRUfAcaskosWc07nARZ"
  },
  "statusCode": 200,
  "message": "Form unlocked successfully.",
  "help": null,
  "status": "success",
  "data": null,
  "error": null
}

Error response (422)

{
  "timestamp": "2026-01-27T04:34:37.668Z",
  "serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "trace": "1LuRUfAcaskosWc07nARZ",
  "path": "/v5/forms/1LuRUfAcaskosWc07nARZ/unlock",
  "pathParams": {
    "trace": "1LuRUfAcaskosWc07nARZ"
  },
  "statusCode": 422,
  "status": "error",
  "message": "Verification status must be 'info' to unlock the form. Current status: 'verified'.",
  "help": null,
  "data": null,
  "error": {
    "type": "validation_error",
    "details": [
      {
        "message": "Verification status is 'verified', expected 'info'.",
        "code": "validation_error",
        "path": ["verificationStatus"]
      }
    ]
  }
}

Error response (404)

{
  "timestamp": "2026-01-27T04:34:37.668Z",
  "serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "trace": "invalidTrace123",
  "path": "/v5/forms/invalidTrace123/unlock",
  "pathParams": {
    "trace": "invalidTrace123"
  },
  "statusCode": 404,
  "status": "error",
  "message": "Not found",
  "help": null,
  "data": null,
  "error": {
    "type": "not_found",
    "details": [
      {
        "message": "Trace not found: invalidTrace123",
        "code": "not_found",
        "path": ["trace"]
      }
    ]
  }
}