> ## Documentation Index
> Fetch the complete documentation index at: https://docs.file.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Update file export status
> This endpoint allows integrated systems to update the export status of a file.
Use this endpoint for pull-based integrations where integrated systems need to report back:
- Whether a file was successfully exported to the integrated system
- Any error messages or status information from the integrated system
The export status and message will be visible in the file list UI.
This endpoint enables **pull-based integrations** to report the export status of files back to fileAI.
## Use Cases
Report when documents have been successfully imported into your ERP system
Confirm invoices have been processed in your accounting platform
Track document processing status in your custom integrations
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 |
```json theme={null}
{
"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
Use `GET /files` with `updatedAfter` to get files that need processing
Download and process files in your integrated system
Call this endpoint to report the export status back to fileAI
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](/docs-api/api-intro#switching-between-instances).
```bash theme={null}
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
```bash theme={null}
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](/docs-api/api-idempotency).
## OpenAPI
````yaml patch /prod/v1/files/{fileId}
openapi: 3.0.0
info:
title: Public API
description: >-
### Welcome to fileAI’s Public API Documentation.
This API allows users to check the health of the system, upload and manage
files, and manage AI Schemas.
Should you have any questions, please reach out to fileAI via the “Contact a
Developer” link below.
[Contact a Developer](mailto:support@file.ai)
### Prerequisites
Before using our API, please ensure you complete the following prerequisites
- You must have a fileAI account. Sign up or login
[here](https://orion.file.ai/en/sign-up)
- You must have an API Key. After creating your fileAI account, you can
generate your API Key. Refer to the Authentication section below for more
details.
### Authentication
All API requests require an API key for authentication.
- To obtain your API key, please log in to your fileAI account and navigate
to Project Settings in your dashboard
- Keep your API key secure and do not share it publicly.
### How to Use Your API Key
Once you have your API key:
- Click the Authorize button on the top-right of this page
- Enter your API Key under Value
- Click Authorize to start making authenticated requests directly from the
documentation
version: '1.0'
contact: {}
servers:
- url: https://api.orion.file.ai
description: Default. Use this unless your workspace is on an instance.
- url: https://api.orion.{instance}.file.ai
description: Instance-specific host.
variables:
instance:
default: au
enum:
- au
- sg
- jp
description: >-
Instance hosting your workspace: au (Australia), sg (Singapore), jp
(Japan).
security: []
tags:
- name: Public API V1
paths:
/prod/v1/files/{fileId}:
patch:
tags:
- Public API V1
summary: Update file export status
description: >-
This endpoint allows integrated systems to update the export status of a
file.
Use this endpoint for pull-based integrations where integrated systems
need to report back:
- Whether a file was successfully exported to the integrated system
- Any error messages or status information from the integrated system
The export status and message will be visible in the file list UI.
operationId: PublicAPIController_updateFileExportStatus
parameters:
- name: fileId
required: true
in: path
schema:
type: string
- name: Idempotency-Key
in: header
description: >-
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.
required: false
schema:
type: string
requestBody:
required: true
description: Export status update payload
content:
application/json:
schema:
type: string
examples:
completed:
summary: Successful export
value:
integrationExportStatus: completed
integrationExportMessages:
- System successfully received result
error:
summary: Failed export
value:
integrationExportStatus: error
integrationExportMessages:
- 'Validation error: Missing required field "invoice_number"'
- Please check the document and retry
exporting:
summary: Export in progress
value:
integrationExportStatus: exporting
integrationExportMessages:
- Queued for processing
responses:
'200':
description: Export status updated successfully
content:
application/json:
example:
fileId: 53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908
exportInfo:
integrationExportStatus: completed
integrationExportMessages:
- System successfully received result
integrationExportUpdatedAt: '2025-01-26T14:30:00.000Z'
schema:
type: object
properties:
fileId:
type: string
description: The file ID
exportInfo:
type: object
description: Export info object matching DocumentExportInfoEntity
properties:
integrationExportStatus:
type: string
enum:
- error
- completed
- exporting
- empty
description: The export status value
integrationExportMessages:
type: array
items:
type: string
description: The export messages (array of strings)
nullable: true
integrationExportUpdatedAt:
type: string
format: date-time
description: Timestamp of the update
'401':
description: Missing or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'403':
description: Read-only or inactive API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'404':
description: File not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
example:
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
'422':
description: Validation error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
example:
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
'429':
description: Rate limit exceeded.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'500':
description: Unexpected internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
security:
- x-api-key: []
components:
schemas:
ProblemDetailsDto:
type: object
properties:
type:
type: string
description: A URI identifying the problem type.
example: https://errors.file.ai/validation-failed
title:
type: string
description: Stable, human-readable summary of the problem type.
example: Validation failed
status:
type: number
description: HTTP status code.
example: 422
detail:
type: string
description: Human-readable explanation specific to this occurrence.
example: One or more fields are invalid.
instance:
type: string
description: URI reference for this occurrence (the request path).
example: /v1/files/upload
code:
type: string
description: Stable machine-readable error code.
example: VALIDATION_FAILED
requestId:
type: string
description: Correlation id for this request.
example: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors:
description: Field-level violations (validation only).
type: array
items:
$ref: '#/components/schemas/ProblemErrorItemDto'
retryAfter:
type: number
description: Seconds until the client may retry (present on 429 only).
example: 42
message:
type: string
description: Legacy key (deprecated — use `detail`/`title`).
example: Validation failed
error:
type: string
description: Legacy key (deprecated — use `title`).
example: Unprocessable Entity
statusCode:
type: number
description: Legacy key (deprecated — use `status`).
example: 422
required:
- type
- title
- status
- detail
- instance
- code
- requestId
- errors
- message
- error
- statusCode
ProblemErrorItemDto:
type: object
properties:
code:
type: string
example: REQUIRED
detail:
type: string
example: must not be empty
pointer:
type: string
description: JSON Pointer to the offending body field.
example: '#/fileName'
parameter:
type: string
description: Name of the offending query/header parameter.
example: limit
required:
- code
- detail
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````