Imports

Start turning an existing document into a template

Paid plans only. Takes a PDF three ways: a multipart file part, a JSON file_url the API fetches (public https only), or JSON { "upload": true }, which answers with a one-time upload link and an import in awaiting_upload. Answers in under a second with the import in uploaded; the work happens after, so poll GET /v1/imports/{id}. The same bytes from the same account inside 24 hours are the same import and answer 200 with existing: true unless force is true. A feature that is switched off on the deployment answers 503 import_disabled.

post/v1/imports

Request

  • Base URL: https://api.galleyrender.com
  • URL: https://api.galleyrender.com/v1/imports
  • Auth: HTTP bearer

Request body

file_urlstring

A public https URL to a PDF. Fetched by the API under the same egress policy as template assets, up to 20 MB and 10 seconds.

uploadtrue

Ask for a one-time upload link instead of sending the file.

forceboolean

Import the same bytes again inside 24 hours instead of returning the earlier import.

Example request

{
  "options": {
    "name": "ashcroft-invoice",
    "hint": "invoice"
  }
}

Response

The same bytes were imported by this account in the last 24 hours; this is that import, with existing: true.

object'import' required
idstring required
status'awaiting_upload' | 'uploaded' | 'reading' | 'analysing' | 'awaiting_answers' | 'answered' | 'synthesising' | 'checking' | 'ready' | 'saved' | 'failed' | 'refused' required

awaiting_upload waits for a file at the upload link. awaiting_answers waits for you. ready is the moment to look at the preview; nothing is a template until saved. failed and refused are final and are not counted against the plan.

kind'pdf' | 'null' nullable

The file type. PDF only for now.

pagesinteger nullable
bytesinteger nullable
document_kindstring nullable

What the analysis took the document to be: invoice, letter, other, and so on.

closest_starterstring nullable

The starter template whose data contract the draft borrows, when one fits. See the docs for what that promises.

languagestring nullable

The document's language, a BCP 47 tag.

delayed_untilstring date-time nullable

When an import waiting to start will be picked up, if the service's daily capacity is used. null when nothing holds it.

notesstring[] required

Things worth knowing, in plain sentences: a font that was substituted, a question that took its recommendation.

preview_urlstring uri nullable

A PDF of the draft rendered from its example, signed for 15 minutes. null until ready.

preview_png_urlstring uri nullable

Page 1 of the preview as a PNG at 1x, signed for 15 minutes, for a client that shows an image rather than a PDF. null until ready, and when none was stored.

preview_expires_atstring date-time nullable
existingtrue

Present, and true, only when this is an earlier import returned for the same bytes.

created_atstring date-time required
completed_atstring date-time nullable
expires_atstring date-time nullable

When the source and its page images are deleted: 7 days after the import finished.

Example response

{
  "id": "imp_4tq8m2x7k1bv",
  "document_kind": "invoice",
  "closest_starter": "invoice",
  "language": "en",
  "questions": [
    {
      "id": "q1",
      "prompt": "Is this paragraph printed the same on every document, or does it change?",
      "options": [
        {
          "value": "field_with_default"
        }
      ]
    }
  ],
  "fonts_substituted": [
    {
      "from": "Helvetica",
      "to": "public-sans"
    }
  ],
  "draft_summary": {
    "fields": [
      "buyer.name",
      "invoice_number",
      "line_items[]"
    ]
  },
  "template": {
    "ref": "ashcroft-invoice@1"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.