Update file export status

curl --request PATCH \
  --url https://api.orion.file.ai/prod/v1/files/{fileId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "integrationExportStatus": "completed",
  "integrationExportMessages": [
    "System successfully received result"
  ]
}
'

{
  "fileId": "53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908",
  "exportInfo": {
    "integrationExportStatus": "completed",
    "integrationExportMessages": [
      "System successfully received result"
    ],
    "integrationExportUpdatedAt": "2025-01-26T14:30:00.000Z"
  }
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "File with id 53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908 not found",
  "instance": "/v1/{route}",
  "code": "NOT_FOUND",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "File with id 53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908 not found",
  "error": "Not Found",
  "statusCode": 404
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "exportStatus is required",
  "instance": "/v1/{route}",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "exportStatus is required",
  "error": "Unprocessable Entity",
  "statusCode": 422
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

PATCH

prod

files

{fileId}

curl --request PATCH \
  --url https://api.orion.file.ai/prod/v1/files/{fileId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "integrationExportStatus": "completed",
  "integrationExportMessages": [
    "System successfully received result"
  ]
}
'

{
  "fileId": "53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908",
  "exportInfo": {
    "integrationExportStatus": "completed",
    "integrationExportMessages": [
      "System successfully received result"
    ],
    "integrationExportUpdatedAt": "2025-01-26T14:30:00.000Z"
  }
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "File with id 53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908 not found",
  "instance": "/v1/{route}",
  "code": "NOT_FOUND",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "File with id 53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908 not found",
  "error": "Not Found",
  "statusCode": 404
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "exportStatus is required",
  "instance": "/v1/{route}",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "exportStatus is required",
  "error": "Unprocessable Entity",
  "statusCode": 422
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

This endpoint enables pull-based integrations to report the export status of files back to fileAI.

Use Cases

ERP Integration

Report when documents have been successfully imported into your ERP system

Accounting Software

Confirm invoices have been processed in your accounting platform

Custom Workflows

Track document processing status in your custom integrations

Error Handling

Report validation errors or processing failures back to users

Request Parameters

Path Parameters

Parameter	Type	Required	Description
fileId	string	Yes	The ID of the file

Request Body

Property	Type	Required	Description
integrationExportStatus	string	Yes	One of `error`, `completed`, `exporting`, `empty`
integrationExportMessages	array of string	No	Messages describing the result from the integrated system

Response

Field	Type	Description
fileId	string	The file ID
exportInfo.integrationExportStatus	string	The stored export status
exportInfo.integrationExportMessages	array of string	The stored messages (nullable)
exportInfo.integrationExportUpdatedAt	string	ISO 8601 timestamp of the update

{
  "fileId": "53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908",
  "exportInfo": {
    "integrationExportStatus": "completed",
    "integrationExportMessages": ["System successfully received result"],
    "integrationExportUpdatedAt": "2025-01-26T14:30:00.000Z"
  }
}

Status Values

Status	Description	When to Use
`completed`	Export successful	Document was successfully processed by integrated system
`error`	Export failed	Validation error, processing failure, or other issues
`exporting`	In progress	Document is queued or being processed
`empty`	No status	Reset/clear the export status

Integration Flow

Fetch Files

Use GET /files with updatedAfter to get files that need processing

Process Files

Download and process files in your integrated system

Report Status

Call this endpoint to report the export status back to fileAI

User Visibility

Users see the status in the fileAI UI, enabling them to track integration progress

Example: Reporting Success

Examples use the default base URL, https://api.orion.file.ai/prod/v1. If your workspace is on an instance-specific host, swap the hostname and change nothing else — see Switching between instances.

curl -X PATCH "https://api.orion.file.ai/prod/v1/files/53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationExportStatus": "completed",
    "integrationExportMessages": ["Successfully imported to SAP"]
  }'

Example: Reporting Error

curl -X PATCH "https://api.orion.file.ai/prod/v1/files/53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationExportStatus": "error",
    "integrationExportMessages": [
      "Validation failed: Invoice number format invalid",
      "Expected format: INV-YYYY-NNNN"
    ]
  }'

The export status and messages are visible in the fileAI file list UI, helping users understand the integration status of their documents.

This endpoint accepts an optional Idempotency-Key request header so a retry cannot apply the change twice. See Idempotent requests.

Authorizations

x-api-key

string

header

required

API key for authentication

Headers

Idempotency-Key

string

Optional opaque key (max 255 chars, UUIDv4 recommended) making this request idempotent for 24h: a retry with the same key and body replays the original response with Idempotent-Replayed: true.

Path Parameters

fileId

string

required

Body

application/json

Export status update payload

The body is of type string.

Response

Export status updated successfully

fileId

string

The file ID

exportInfo

object

Export info object matching DocumentExportInfoEntity

Show child attributes

fileAI API

Key Functions

Endpoints

Agent (v2)

Update file export status

Use Cases

ERP Integration

Accounting Software

Custom Workflows

Error Handling

Request Parameters

Path Parameters

Request Body

Response

Status Values

Integration Flow

Example: Reporting Success

Example: Reporting Error

Authorizations

Headers

Path Parameters

Body

Response

​Use Cases

ERP Integration

Accounting Software

Custom Workflows

Error Handling

​Request Parameters

​Path Parameters

​Request Body

​Response

​Status Values

​Integration Flow

​Example: Reporting Success

​Example: Reporting Error

Authorizations

Headers

Path Parameters

Body

Response

Use Cases

Request Parameters

Path Parameters

Request Body

Response

Status Values

Integration Flow

Example: Reporting Success

Example: Reporting Error