Skip to navigation
Paperwork APIEmbeds

Create an embed session

View as Markdown

Creates a session for an embedded view and returns its iframe url.

Call this from your backend with your API key. Put url in the src of an iframe on one of the origins pages. The URL carries a short-lived token in its fragment: treat it as a secret, and create a new session for each person and each visit.

A review session binds one extraction run (exr_…) with unit per_document and 1 to 20 of its documents. In write mode the person can edit and approve values. webhook then receives each save and approval.

A transcript or document session binds one ready file, in read mode. transcript needs a transcribed audio file. document needs a PDF, an office file with a preview, or an image.

The session ends at expiresAt: the earliest of now plus ttl and the run expiry. Call DELETE /v1/embeds/{id} to end it sooner.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
originslist of stringsRequired

The exact origins of the pages that frame the view, such as https://app.example.com. No path, no wildcard, no trailing slash.

viewenumOptionalDefaults to review

The embedded view. review shows the results of an extraction run. transcript shows an audio file with its speaker transcript. document shows a PDF, an office file preview or an image. transcript and document are read only.

Allowed values:
runobjectOptional

The extraction run (exr_…) to review.

documentslist of stringsOptional
The file ids of the run to show, in this order. The default is every finished document of the run, in run order.
fileobjectOptional

The file to show (transcript and document views).

spaceobjectOptional

The space of file (transcript and document views). The default is the files of /v1/files.

modeenumOptionalDefaults to read

write lets the person edit and approve the values.

Allowed values:
userobjectOptional
The person who uses the embedded view, as your system knows them. It is stored as claimed and marked unverified. The email is never sent in a webhook or an audit event.
webhookobjectOptional

Where to deliver this run's events, given one of two ways.

  • { "url": "…" } — a one-off https endpoint for this run only.
  • { "id": "whe_…" } — a saved endpoint from POST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.

Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.

themeobjectOptional
The look of the embedded view. The mode is fixed for the session.
localeenumOptionalDefaults to en
Allowed values:
metadatamap from strings to anyOptional

Arbitrary JSON you attach to the run and get back on every read of it.

Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.

ttlintegerOptional60-28800Defaults to 3600

Session lifetime in seconds (60 to 28800). The session also ends when the run expires.

Response

The session, with the iframe url.

object"embed_session"
idstring
viewenum
Allowed values:
modeenum
Allowed values:
urlstring

The iframe src. It carries the session token in its fragment: treat it as a secret.

documentslist of strings
expiresAtstring
createdAtstring
runobjectOptional
fileobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
410
Gone Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error