Skip to main content
POST
/
v1
/
documents
Upload a file and create a document
const form = new FormData();
form.append('file', '<string>');
form.append('title', 'Q4 Financial Report');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.factify.com/v1/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "doc_01h2xcejqtf2nbrexx3vqjhp41",
  "org_id": "org_01h2xcejqtf2nbrexx3vqjhp41",
  "title": "Q4 Financial Report",
  "is_demo": false,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:35:00Z",
  "created_by": {
    "id": "usr_01h2xcejqtf2nbrexx3vqjhp41",
    "name": "Alice Chen"
  },
  "url": "https://app.factify.com/documents/doc_01h2xcejqtf2nbrexx3vqjhp41",
  "description": "<string>",
  "current_version": {
    "id": "ver_01h2xcejqtf2nbrexx3vqjhp41",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "trashed_at": "2023-11-07T05:31:56Z",
  "last_viewed_at": "2023-11-07T05:31:56Z",
  "shared_at": "2023-11-07T05:31:56Z",
  "thumbnail_url": "<string>",
  "capabilities": {
    "attach_policy": true,
    "comment_private": true,
    "comment_public": true,
    "copy_content": true,
    "create_version": true,
    "export": true,
    "grant_access": true,
    "list_versions": true,
    "manage_access": true,
    "open": true,
    "screenshot": true,
    "trash": true,
    "view": true,
    "view_analytics": true,
    "view_leads": true,
    "view_timeline": true
  },
  "current_version_full": {
    "id": "ver_01h2xcejqtf2nbrexx3vqjhp41",
    "document_id": "doc_01h2xcejqtf2nbrexx3vqjhp41",
    "created_at": "2025-01-15T10:30:00Z",
    "created_by": {
      "id": "usr_01h2xcejqtf2nbrexx3vqjhp41",
      "name": "Alice Chen"
    },
    "status_error": "unsupported file format"
  }
}

Documentation Index

Fetch the complete documentation index at: https://developers.factify.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication using a factapi-issued API key (ffy_<env>_<base32_uuid><base62_random>). Cookie-based sessions are accepted automatically by user-facing endpoints but are not surfaced as an OpenAPI auth scheme.

Query Parameters

​
title
string

Optional title for the document. Defaults to the uploaded filename.

Example:

"Q4 Financial Report"

Body

multipart/form-data
​
file
file
required

The file to process

​
title
string

Optional title. Defaults to filename when omitted.

Example:

"Q4 Financial Report"

Response

Created

A document with metadata, processing state, access policy, and the caller's per-action capabilities. Embeds a current_version reference to the most recent version for status checks; full version history is available via listVersions.

​
id
string
required

Unique document ID. Pattern doc_[0-9a-hjkmnp-tv-z]{26}.

Example:

"doc_01h2xcejqtf2nbrexx3vqjhp41"

​
org_id
string
required

ID of the organization that owns the document.

Example:

"org_01h2xcejqtf2nbrexx3vqjhp41"

​
title
string
required

Human-readable document title. Defaults to the uploaded filename if not specified at create time.

Example:

"Q4 Financial Report"

​
is_demo
boolean
default:false
required

True for the seed demo document minted by the new-user provisioning flow. Workspace OnboardingTour gates on this.

Example:

false

​
processing_status
enum<string>
required

Lifecycle state of a document version's ingestion pipeline.

Available options:
pending,
processing,
ready,
failed
​
source_type
enum<string>
required

Origin file format of an uploaded document version.

Available options:
pdf,
docx,
xlsx,
csv,
markdown
​
access_level
enum<string>
required

Document access level. Aligned with v1beta SDK enum exactly.

Available options:
private,
organization,
public
​
created_at
string<date-time>
required

Timestamp when the document was first created.

Example:

"2025-01-15T10:30:00Z"

​
updated_at
string<date-time>
required

Timestamp of the last metadata or version change.

Example:

"2025-01-15T10:35:00Z"

​
created_by
object
required

Subject is a lightweight reference to either a user or a bot. Used in embedded fields like created_by. For full details, call GetUser or GetBot with the subject's id.

​
url
string
required

Deeplink URL for accessing the document in the Factify web app.

Example:

"https://app.factify.com/documents/doc_01h2xcejqtf2nbrexx3vqjhp41"

​
description
string | null

Optional document description.

Maximum string length: 10000
​
current_version
object

Lightweight reference to a document version.

​
trashed_at
string<date-time>

Timestamp when the document was moved to trash. Absent for non-trashed documents.

​
last_viewed_at
string<date-time>

Timestamp when the authenticated user last viewed this document. Absent if the user has never viewed it.

​
shared_at
string<date-time>

Timestamp when this document was last shared to the authenticated user. Absent if the document was never shared to them.

​
thumbnail_url
string

URL of the document thumbnail image. May be absent before the first ingestion completes.

​
capabilities
object

Permissions the authenticated user has on a document. Each field is optional; absent means the capability is not known or not evaluated.

​
current_version_full
object

Expanded current-version payload. Populated only when GetDocument is called with ?include=current_version; absent on List responses and on Get without the include. The lightweight current_version reference remains populated regardless. Carries the version's creator as an embedded Subject (created_by).