API Reference
Start typing to search…

Rerun file form filling

patch https://api.orion.file.ai/prod/v1/files/schema/rerun

This endpoint is used to rerun the form filling of a file.

It is used to update the file fields based on the current file content and the current schema version.

The fileId field is used to specify the file that should be updated.

The backgroundRerun field is used to determine whether the form filling should be run in the background. If set to true, the form filling will be run in the background. If set to false, the form filling will be run synchronously.

The rerunOptions field is used to specify the options for the form filling. The allowed fields are paths, partialRerun, and notification.

The paths field is used to specify the fields that should be updated. The fields that are specified in the paths field will be updated with the new schema fields.

The partialRerun field is used to determine whether the form filling should only be run for the modified fields. If set to true, the form filling will only be run for the modified fields. If set to false, the form filling will be run for all fields.

The notification field is used to specify the notification options for the form filling. The allowed fields are shouldSendOnCompletion, referenceEntityName, referenceEntityId, and referenceEntityAction.

The shouldSendOnCompletion field is used to determine whether a notification should be sent when the form filling is completed. If set to true, a notification will be sent when the form filling is completed. If set to false, no notification will be sent.

The referenceEntityName field is used to specify the name of the reference entity that should be used for the notification. The allowed values are FILE and SCHEMA.

The referenceEntityId field is used to specify the id of the reference entity that should be used for the notification.

The referenceEntityAction field is used to specify the action that should be used for the notification. The allowed values are CREATE, UPDATE, and DELETE.

Overview

This endpoint triggers a reprocessing of file data to ensure all fields are populated according to the current schema definition. Use this when:

  • Schema has been updated since the file was last processed
  • File content has changed and needs re-analysis
  • Specific fields need to be refreshed with new extraction logic

Request Body

ParameterTypeRequiredDescription
fileIdstringYesUnique identifier of the file to reprocess
backgroundRerunbooleanNoExecute processing asynchronously (default: false)
rerunOptionsobjectNoConfiguration options for the rerun process

Rerun Options Object

PropertyTypeRequiredDescription
pathsarrayNoSpecific field paths to update (if not provided, all fields are processed)
partialRerunbooleanNoOnly process modified fields (default: false)
notificationobjectNoNotification settings for completion alerts

Notification Object

PropertyTypeRequiredDescription
shouldSendOnCompletionbooleanNoSend notification when processing completes (default: false)
referenceEntityNamestringNoEntity type for notification context: FILE or SCHEMA
referenceEntityIdstringNoID of the reference entity for notification
referenceEntityActionstringNoAction type for notification: CREATE, UPDATE, or DELETE

Processing Modes

Synchronous Processing

  • Set backgroundRerun: false (default)
  • API call waits for completion before returning
  • Suitable for immediate results or small files
  • Response includes processing results

Asynchronous Processing

  • Set backgroundRerun: true
  • API call returns immediately with job ID
  • Suitable for large files or batch processing
  • Use webhooks or polling to check completion status

Example Request

{
  "fileId": "8123612d-187c-44eb-8ac6-214e68506b7e",
  "backgroundRerun": true,
  "rerunOptions": {
    "paths": [
      "/discount_amount"
    ],
    "partialRerun": true
  }
}

Partial Rerun with Specific Fields

{
  "fileId": "file-abc-123",
  "backgroundRerun": false,
  "rerunOptions": {
    "paths": [
      "invoice_number",
      "invoice_date", 
      "invoice_total"
    ],
    "partialRerun": true
  }
}

Background Rerun with Notifications

{
  "fileId": "file-abc-123",
  "backgroundRerun": true,
  "rerunOptions": {
    "partialRerun": false,
    "notification": {
      "shouldSendOnCompletion": true,
      "referenceEntityName": "FILE",
      "referenceEntityId": "file-abc-123",
      "referenceEntityAction": "UPDATE"
    }
  }
}

Complete Configuration Example

{
  "fileId": "file-abc-123",
  "backgroundRerun": true,
  "rerunOptions": {
    "paths": [
      "document.metadata",
      "extracted.fields"
    ],
    "partialRerun": true,
    "notification": {
      "shouldSendOnCompletion": true,
      "referenceEntityName": "SCHEMA",
      "referenceEntityId": "schema-def-456",
      "referenceEntityAction": "UPDATE"
    }
  }
}

Best Practices

  1. Use asynchronous processing for large files or batch operations to avoid timeouts
  2. Specify field paths when only certain fields need updating to improve performance
  3. Enable notifications for background jobs to track completion status
  4. Use partial reruns when only schema-modified fields need processing
  5. Handle conflicts gracefully when files are already being processed
  6. Validate field paths before submission to avoid processing errors

Performance Considerations

  • Full reruns process all fields and may take longer
  • Partial reruns only process specified paths, improving speed
  • Background processing prevents API timeouts for large files
  • Field path specificity reduces processing overhead
  • Schema version alignment ensures optimal extraction accuracy
Language
Credentials
Header
Click Try It! to start a request and see the response here!