---
title: "POST /documents/{document_id}/prefills"
method: POST
path: "/documents/{document_id}/prefills"
tags: ["Prefill"]
---

# POST /documents/{document_id}/prefills

`POST /documents/{document_id}/prefills`

## Request

- Base URL: `https://api-docs.simplepdf.com/api/v1`
- URL: `https://api-docs.simplepdf.com/api/v1/documents/{document_id}/prefills`
- Auth: HTTP bearer

Create a prefill, then send the prefill blob directly to your own storage by PUTting it to the `url` in the returned `upload` object with its `headers`. The blob is a JSON document of shape `{ "fields": [{ "id": "<field id>", "value": "<value>" }] }`. Each `id` is a field `id` from `GET /documents/{document_id}/fields`; each `value` is a string for text and checkbox fields, a base64 data URL (for example `data:image/png;base64,...`) for signature and picture fields, or one of the listed `options` when the field is constrained. Signatures look best as a transparent PNG at roughly a 3:1 aspect ratio (for example 1200x400). Unknown ids are ignored and read-only fields ignore prefill values. Returns an `embed_url` a recipient opens to review and submit. Requires your own storage (S3, Azure Blob Storage, or SharePoint) that allows read access (write-only storage cannot serve the blob back to recipients) and a document with configured fields.

## Path parameters

- `document_id` string, uuid, required

## Request body

- object
  - `context` object, nullable: Optional correlation metadata delivered inline to the submission webhook. Do NOT put sensitive information here. PII belongs in the prefill blob (customer storage).

## Response `200`

Successful response

- object
  - `id` string, required
  - `created_at` string, required
  - `upload` union, required: Where and how to send the prefill blob: PUT a JSON body of shape `{ "fields": [{ "id": "<field id>", "value": "<value>" }] }` to this `url` with these `headers`.
    - object
      - `type` 'presigned_put', required
      - `url` string, required
      - `method` 'PUT', required
      - `headers` object, required
    - object
      - `type` 'graph_upload_session', required
      - `url` string, required
      - `method` 'PUT', required
      - `headers` object, required: Send these headers, and additionally compute and add `Content-Length: <blob byte length>` and `Content-Range: bytes 0-<blob byte length - 1>/<blob byte length>` for this upload type (the byte length is only known once you have the blob).
  - `embed_url` string, required: Link a recipient opens to review and submit the prefilled document (standalone or embedded).

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `404`: Not found
- `409`: Conflict
- `429`: Too many requests

---

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