---
title: "Create and analyze a document asynchronously"
method: POST
path: "/api/v1/documents"
tags: ["Documents"]
---

# Create and analyze a document asynchronously

`POST /api/v1/documents`

## Request

- Base URL: `https://www.ifillpdf.com`
- URL: `https://www.ifillpdf.com/api/v1/documents`
- Auth: HTTP bearer

Creates a document, debits quota, renders page images when possible, starts semantic analysis, and returns 202 for polling. Poll GET /api/v1/documents/{id} until status changes.

## Request body

- union
  - object
    - `pending_upload_id` string, required
    - `pdf_url` string, uri
    - `name` string
    - `description` string
    - `suggested_entities` SuggestedEntity[]
      - `id` string, required
      - `label` string, required
      - `color` string
      - `source` 'user' | 'history'
  - object
    - `pending_upload_id` string
    - `pdf_url` string, uri, required
    - `name` string
    - `description` string
    - `suggested_entities` SuggestedEntity[]
      - `id` string, required
      - `label` string, required
      - `color` string
      - `source` 'user' | 'history'

## Response `202`

Analysis started.

- DocumentStartResponse
  - `document_id` string, uuid, required
  - `status` 'analyzing', required
  - `page_count` integer, required
  - `page_images_ready` boolean
  - `page_images_count` integer
  - `preview_image_url` string, nullable
  - `quota` Quota, required
    - `remaining` integer
    - `plan` string

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid API key.
- `402`: Team page quota is exhausted.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/ifillpdf/apis/ifillpdf-api.md) · [All operations](https://skmtc.dev/ifillpdf/apis/ifillpdf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ifillpdf/apis/ifillpdf-api/revisions/17d927bde9ea?raw)