# Welcome to Insly AI

These pages serve to explain Insly's AI-driven products.&#x20;

Should you have further questions, please reach out to us:

* Roald Sinissaar – AI Product Owner – <roald.sinissaar@insly.com>
* Morten Jõgi – Project Manager – <morten.jogi@insly.com>

### Explore:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-bolt">:bolt:</i></h4></td><td><strong>Nora</strong></td><td>Insly's format-agnostic data extraction engine for claims and underwriting processes</td><td></td><td></td><td><a href="https://docs.ai.insly.com/nora/introduction">Introduction</a></td></tr></tbody></table>


# Introduction

Nora is an AI layer that augments insurance operations. It extracts, understands, follows up, triages, and orchestrates workflows across submissions, underwriting, and claims. Modular by design, Nora integrates with existing systems and can be deployed via API, MCP, or embedded workflows.


# Terminology

### Submission <a href="#submission" id="submission"></a>

End users create Submissions, which are some collection of input that will be processed by AI, reviewed and confirmed by a human, and be exposed to downstream processes. One may be created via the web UI by submitting files, or by sending an email with attachments to a predefined email address.

A Submission may have one or more Files attached, and will require a Template to be processed.

### File <a href="#file" id="file"></a>

A document submitted by an end user. Currently, Nora accepts the following file formats:

* pdf
* doc, docx
* csv
* xls, xlsx
* gif, png, jpg or jpeg, heic

Documents may be converted to PDFs for processing and display, which means some files (notably Excel spreadsheets) may look different after processing. This does not affect the quality of data extraction.

### Template <a href="#template" id="template"></a>

Each submission must have a template assigned - this is to guide the AI agent in extraction, and defines the fields and structure that you wish to extract. Fields may be text or number fields, take single values or an enum of different values.

You may also define discrete sections and allow lists of multiple objects.

Each field in the template also takes an optional "AI hint", which aids the AI agent in data extraction. In many cases, this is not needed as the structure and field titles are descriptive enough (e.g. `Applicant` > `First name` is plenty), but it can be helpful in other cases (e.g. `Applicant` > `Country of residence` may take the hint `If this is not stated in the source document, infer it from the correspondence address`). See [Writing AI hints](https://docs.ai.insly.com/nora/configuration-guide/writing-ai-hints) for how to write them, with examples.

The "shape" of the template also dictates how the final JSON-formatted payload will look. For example:

<figure><img src="https://4110327221-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIl1X3JAZ6wvoa5MKf9ny%2Fuploads%2F2X8nSj2Ei8fYsqtEbGIR%2Fc7b1482f-86a7-4759-82b3-689ccca04236.png?alt=media&amp;token=b75fb13f-66ca-4e4f-baf5-5a6af47ea559" alt=""><figcaption></figcaption></figure>

Ex:

* Curly braces {} indicate key in payload.
* Single arrow down represents a JSON object.
* Double arrow down represents an array of objects.
* *Aa* means the field is a string

This template in example could result in payload structured like:

```json
{
  "customer": {
    "firstName": "John",
    "surname": "Wick"
  },
  "risk": {
    "zip": "12345",
    "street": "Main Street",
    "city": "New York",
    "country": "USA",
    "county": "New York"
  },
  "valueableItems": [
    {
      "name": "Gold",
      "value": "10000"
    },
    {
      "name": "Diamonds",
      "value": "I think about 4000$"
    },
    {
      "name": "Fake Rolex",
      "value": "100 - more sentimental value"
    }
  ]
}
```


# Onboarding

Setup and the input we need from you.

## How to use this guide

* **This page:** what Nora is and the ways you can use it.
* **The topic pages below:** each topic in detail.
* [**What we need from you, and when**](https://docs.ai.insly.com/nora/onboarding/what-we-need-from-you-and-when)**:** every input we need, with its deadline. This will be your checklist. Start here if you already know Nora.

Every input carries one of three deadlines:

| Deadline       | Meaning                                                                             |
| -------------- | ----------------------------------------------------------------------------------- |
| 🔴 **ASAP**    | At kick-off. Blocks work: nothing can be built until it arrives or takes more time. |
| 🟡 **TESTING** | Needed to test in Demo. The earlier it arrives, the earlier you can start testing.  |
| 🟢 **GO-LIVE** | Before rollout. Production (live) setup only.                                       |

## Nora at a glance

Nora reads insurance submissions (emails, PDFs, spreadsheets, Word files), extracts the data into your product’s fields, checks that it is complete and, optionally, creates the quote in Insly Ledger.

| Step          | What happens                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 1. Intake     | A submission arrives by email or is uploaded in the Nora web app.                                                              |
| 2. Extraction | AI reads every attached file and the email body and fills in your product’s fields.                                            |
| 3. Validation | Nora checks required fields, allowed values (e.g. dropdown options) and formats.                                               |
| 4. Follow-up  | Email intake only. If required details are missing, Nora emails the sender for them and adds the reply to the same submission. |
| 5. Review     | Your team checks and corrects the data in the Nora web app: every submission, or a sample.                                     |
| 6. Completion | The quote is ready. Optionally it can be exported to Insly Ledger.                                                             |

**Two environments**

* **Demo:** for testing (optionally connected to your Ledger test environment).
* **Production (live):** for live use (optionally connected to Ledger production environment).
* Each has its own configurations such as users, whitelisted addresses and broker mappings, so most inputs are asked for each environment.

## Choose how you’ll use Nora

|                               | Web app only                             | Email only                        | Email + web app                      |
| ----------------------------- | ---------------------------------------- | --------------------------------- | ------------------------------------ |
| How submissions arrive        | Your team uploads files in the web app   | Senders email a dedicated address | Both                                 |
| Follow-up for missing details | No: your team fills gaps in review       | Yes, by email to the sender       | Yes, for emailed submissions         |
| Export to Ledger              | An approver exports each submission      | Automatic once complete           | Uploads: approver; emails: automatic |
| Who needs a web app login     | Everyone who uploads, reviews or exports | Reviewers only; senders never do  | Both groups                          |

**Decide:** which mode to use, and for which product(s). 🔴 **ASAP**


# Sample submissions and golden records

## What it is

Real submissions paired with their “perfect” result. They are the baseline we measure Nora’s extraction against, and we write extraction hints from them. We rerun the comparison after every change to Nora, to confirm improvements and catch regressions.

## What you decide

* Which submissions to use: 5–10 realistic ones (the more the better), from simple to the most complex, covering the file types your senders actually send.

## What to send us

* The submissions as received (email + attachments).
* With Ledger export: link to each quote, filled in by hand in your Ledger demo environment.
* Without Ledger export: the expected result per submission, in a format we agree with you.

## When

🔴 **ASAP** Blocks extraction improvement work.

## Good to know

* Leave a field empty when the submission doesn’t answer it, even if you would normally find the answer elsewhere. Fill in only what the submission itself contains (email body + attachments). Anything added from elsewhere would count as an error Nora couldn’t have avoided.
* Fill in what your underwriter would choose.

Related: [Processing limitations](https://docs.ai.insly.com/nora/processing-limitations)


# Intake and email address

## What it is

The address senders email submissions to. Nora’s follow-up emails and the senders’ replies go through it. Each product has its own Nora address per environment, and Nora picks the product from the address a submission arrives at.

## What you decide

* **Option 1, Nora address:** senders email the address we create per product (e.g. <yourcompany+product@formflow-email.net>). Ready straight away, no IT work.
* **Option 2, your own mailbox:** senders email an address on your domain, which redirects everything to the Nora address. Nora’s emails are also sent from it, and replies go back to it (see [Branding and email masking](https://docs.ai.insly.com/nora/onboarding/branding-and-email-masking)). Use one mailbox per environment and product, e.g. <nora-demo-productA@yourcompany.com> and <nora-productA@yourcompany.com>, so test and live submissions stay separate.
* **Optional, copies of Nora’s emails:** every email Nora sends can be BCC’d to your mailbox, so you see the full conversation.

## What to send us

* Chosen option.
* For option 2: a mailbox address per environment and product, and an IT contact for the DNS records.
* Whether you want BCC copies.

## When

* Decision: 🔴 **ASAP**
* Option 2 mailbox tested in Demo and working: 🟢 **GO-LIVE**

## Good to know

* **How option 2 works:** senders email your mailbox → it redirects to the Nora address → Nora replies from your mailbox → the sender’s reply lands in your mailbox and is redirected to Nora again. To senders, every email comes from you.
* **DNS setup for option 2:** sending from your domain needs three DNS records. We send them, your IT adds them (usually a 5-minute change), they take effect within a few hours, and we confirm once verified. We then test the full flow in Demo and Prod.
* The redirect must keep the original sender: the email reaching Nora must still read “From: <john@broker.com>”, not your mailbox. Otherwise broker mapping won’t work.
* You can start on option 1 and move to option 2 later if you wish.
* A submission sent to another product’s address is read against that product. Make sure every submission reaches its own product’s address.
* With BCC copies, your redirect rule must skip the emails Nora sends. Otherwise each copy is processed again as a new submission.

Related: [Email intake and Email whitelisting](https://docs.ai.insly.com/nora/skills/email-intake-and-email-whitelisting)


# Fields + required/optional

## What it is

The fields Nora extracts, selected from your Ledger product. We send you the full list prefilled in a field sheet (sent separately); you mark each field.

## What you decide

* Per field: **keep** or **discard** in Nora.
* Per kept field: **required** or **optional**.
* Optional: an **extraction hint** per field, e.g. “Use the year of manufacture, not the registration year.” See [Writing AI hints](https://docs.ai.insly.com/nora/configuration-guide/writing-ai-hints).

## What to send us

* The completed field sheet (sent separately).

## When

🔴 **ASAP** This is the core of the setup. Testing starts once it is applied.

## Why discard fields

* **Higher accuracy:** the AI keeps track of fewer fields per submission, so it confuses similar fields less often. Fewer failures on larger files.
* **Faster processing:** less to consider in extraction.
* **Less to review:** reviewers only see what matters.
* Discarded fields can still be completed in Ledger.

## What “required” does

* A missing required field blocks export.
* For emailed submissions, Nora asks the sender for it by email.

| Nora can require                                | Nora can’t require                                                                                                                       |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| A field that must always be filled              | A field that applies only when another answer is X (e.g. “bankruptcy details”, needed only when the “has been bankrupt” answer is “Yes”) |
| A value from a fixed list (dropdown)            | One of two fields where only one ever applies (e.g. Property Owners vs Project Public Liability)                                         |
| A number of list items (e.g. at least 1 driver) |                                                                                                                                          |
| A valid format (date, number, email)            |                                                                                                                                          |

A couple of examples that illustrate the issues with marking conditional fields as mandatory (also referenced in the table):

* The **“Bankruptcy details”** field under **“Has been declared bankrupt?”** will only need to be populated when that question is answered **“Yes”**. Answer **“No”** and those details will not be needed. Made mandatory, every submission would get an email asking the sender to describe a bankruptcy even if that never happened.
* Two fields where only one can ever apply. For example, if you answer **“Yes”** to **“Are you appointing a main contractor who will be in full control of the site?”** then **“Property Owners Liability”** becomes relevant, but if you answer **“No”** then **“Project Public Liability”** becomes relevant. Never both. Marking both mandatory would mean not being able to create the quote due to wrong fields blocking the export.

Conditional fields therefore stay optional. We add hints so the AI fills them whenever the source contains the answer, and your team completes the rest in review.

## Before making a field required, check where the answer comes from

| Situation                        | Recommendation                                                                                              |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| On the form and usually answered | Require it: follow-up catches anything the AI missed.                                                       |
| On the form but often left blank | Require it: follow-up collects the answer.                                                                  |
| Not on the form at all           | Usually keep it optional or discard field from Nora: otherwise every submission triggers a follow-up email. |


# Review and export

## What it is

How a completed submission reaches Ledger.

* **Uploaded in the web app:** always waits for an approver to export it.
* **Emailed:** exported automatically once complete.

## What you decide

* Whether to export to Ledger.

## What to send us

* Whether to set up export to Ledger.

## When

* Decision: 🔴 **ASAP**

Related: [Exporting to Ledger](https://docs.ai.insly.com/nora/configuration-guide/insly-ledger-integration/exporting-to-ledger)


# Web app access and roles

## What it is

Who can log in to the Nora web app (studio.ai.insly.com) and what they can do. Senders who only email never need a login.

## What you decide

* A role for each user:

| Role     | Can do                                          |
| -------- | ----------------------------------------------- |
| Viewer   | See submissions and extracted data; no changes. |
| Editor   | See and correct data; cannot export.            |
| Approver | See, correct and export to Ledger.              |

## What to send us

* Per environment: email address + role for each user. For Prod, “same as Demo” is enough if that’s the case.
* Whether two-factor authentication should be set up in the tenant.

## When

* Demo: 🟡 **TESTING**
* Prod: 🟢 **GO-LIVE**

## Good to know

* Anyone who pushes quotes into Ledger must be an Approver.
* Two-factor authentication will be set up at first login, if required.

Related: [Role-based access](https://docs.ai.insly.com/nora/skills/role-based-access), [Multi-factor authentication](https://docs.ai.insly.com/nora/configuration-guide/multi-factor-authentication)


# Sender whitelist

## What it is

The senders allowed to submit to your Nora address. Emails from anyone else are not processed. Optional: without a list, anyone can submit.

## What you decide

* Whitelist or open.
* Whitelist by **domain** (@broker.com), **address** (<jane@broker.com>) or both.

## What to send us

* One list per environment.

## When

* Demo: 🟡 **TESTING**
* Prod: 🟢 **GO-LIVE**

## Good to know

* Domains are low-maintenance. Address lists need updating whenever a broker’s staff changes.
* Include your own domain so your team can send test submissions.
* For a phased launch, start with a few broker domains and add more as you roll out.

Related: [Email intake and Email whitelisting](https://docs.ai.insly.com/nora/skills/email-intake-and-email-whitelisting)


# Broker mapping

## What it is

Decides which broker is attached to the quote in Ledger, based on who sent the email. More reliable than AI extracting the broker from the documents.

## What you decide

* **Broker from Ledger user OR from a mapping:** A) Broker from Ledger user means fetching the user that corresponds to the sender’s email and taking the broker from there. It also sets that user as the quote’s agent. No list to maintain, but senders must be Ledger users. B) A mapping is a manually compiled list which maps sender address or domain to Ledger broker entity. An address match beats a domain match. The list needs to be maintained.
* **Broker required in follow-up OR fallback broker:** A) Required in follow-up – When no broker matched in extraction, a follow-up will go out to ask for one. B) When broker not required, but no broker matched in extraction, it’s possible to choose one specific Ledger broker to fall back to for all submissions.

## What to send us

* A) Broker from Ledger user OR B) from a mapping?
  * If A, confirm that senders are Ledger users.
  * If B, in the mapping, use broker names exactly as they appear in Ledger.
* A) Broker required in follow-up OR B) fallback broker?

## When

* Demo test decisions and mapping: 🟡 **TESTING**. Map a few of your own team’s addresses to test brokers so you can check the result in Ledger.
* Prod decisions and mapping: 🟢 **GO-LIVE**

## Good to know

* A broker name that doesn’t match anything in Ledger is ignored, never written to the quote.


# Email templates

## What it is

The automated emails Nora sends to senders (email intake only):

| Email                  | Sent when                                                          |
| ---------------------- | ------------------------------------------------------------------ |
| Acknowledgement        | A submission is received.                                          |
| Missing information    | Required details are missing. Lists them for the sender to answer. |
| Passed to underwriters | The quote is created in Ledger.                                    |
| Technical issue        | Processing failed.                                                 |

## What you decide

* Wording changes per email: tone, sign-off, contact details, disclaimers, footer (e.g. regulatory text).

## What to send us

* The completed template input sheet (sent separately), with the current wording.

## When

🟡 **TESTING** so testers see the final wording.

## Good to know

* Senders answer the missing-information email in free text; Nora adds the answers to the same submission.

Related: [Email notifications](https://docs.ai.insly.com/nora/configuration-guide/email-notifications), [Email Follow Up](https://docs.ai.insly.com/nora/skills/email-follow-up)


# Branding and email masking

## What it is

How Nora appears to your senders.

## What you decide

* **Look:** banner or logo, background colour, font.
* **Sending address (email masking):** emails come from Nora’s address, or from yours (e.g. <nora-demo-productA@yourcompany.com>). Same setup as option 2 in [Intake and email address](https://docs.ai.insly.com/nora/onboarding/intake-and-email-address).

## What to send us

* Any branding needs.
* Sending address, if masked.

## When

🟡 **TESTING**


# Testing, go-live and hypercare

## What it is

The route from Demo testing to steady live use.

## What you decide

* Go-live date.
* First group of senders (a phased launch is recommended).

## What to send us

* Expected volumes: per day and per month at launch, plus a realistic near-future figure. We use them to plan capacity.
* Test results: for each issue, the submission link plus what you expected.

## When

* Volumes: 🟡 **TESTING**
* Go-live date and first senders: 🟢 **GO-LIVE**

## Testing in Demo

* Use as many real, varied submissions as possible: different brokers, formats and levels of completeness.
* Test the whole route: send, receive follow-up, reply, check the quote in Ledger.

## Hypercare (first weeks live)

* Insly may spot-check some submissions before export to verify the data. Checked submissions continue automatically straight after.
* Priority support after go-live.

Related: [Set up human spot checks](https://docs.ai.insly.com/nora/configuration-guide/set-up-human-spot-checks)


# What we need from you, and when

Each confirmation unblocks work on our side, so send inputs as they are ready rather than all at once.

## 🔴 ASAP: at kick-off

| Input                                              | Topic                                                                                                                    | Applies to |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------- |
| Operating mode (web app / email / both)            | [Choose how you’ll use Nora](https://docs.ai.insly.com/nora/onboarding#choose-how-youll-use-nora)                        | All        |
| 5–10 sample submissions + a golden record for each | [Sample submissions and golden records](https://docs.ai.insly.com/nora/onboarding/sample-submissions-and-golden-records) | All        |
| Fields to keep or discard                          | [Fields + required/optional](https://docs.ai.insly.com/nora/onboarding/fields-+-required-optional)                       | All        |
| What is required/optional                          | [Fields + required/optional](https://docs.ai.insly.com/nora/onboarding/fields-+-required-optional)                       | All        |
| Intake option: Nora address or your own mailbox    | [Intake and email address](https://docs.ai.insly.com/nora/onboarding/intake-and-email-address)                           | Email      |
| Whether to export to Ledger                        | [Review and export](https://docs.ai.insly.com/nora/onboarding/review-and-export)                                         | All        |

## 🟡 TESTING: before testing in Demo

| Input                                                                              | Topic                                                                                                     | Applies to |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- |
| Demo UI users and roles                                                            | [Web app access and roles](https://docs.ai.insly.com/nora/onboarding/web-app-access-and-roles)            | All        |
| Two-factor authentication (yes / no)                                               | [Web app access and roles](https://docs.ai.insly.com/nora/onboarding/web-app-access-and-roles)            | All        |
| Demo sender whitelist                                                              | [Sender whitelist](https://docs.ai.insly.com/nora/onboarding/sender-whitelist)                            | Email      |
| Demo broker source (Ledger user / mapping) + missing broker (follow-up / fallback) | [Broker mapping](https://docs.ai.insly.com/nora/onboarding/broker-mapping)                                | Email      |
| Email template changes                                                             | [Email templates](https://docs.ai.insly.com/nora/onboarding/email-templates)                              | Email      |
| Branding and sending address                                                       | [Branding and email masking](https://docs.ai.insly.com/nora/onboarding/branding-and-email-masking)        | Email      |
| BCC copies of Nora’s emails (yes / no)                                             | [Intake and email address](https://docs.ai.insly.com/nora/onboarding/intake-and-email-address)            | Email      |
| Expected volumes at go-live                                                        | [Testing, go-live and hypercare](https://docs.ai.insly.com/nora/onboarding/testing-go-live-and-hypercare) | All        |

## 🟢 GO-LIVE: before rollout

| Input                                                                              | Topic                                                                                                     | Applies to |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- |
| Prod UI users and roles                                                            | [Web app access and roles](https://docs.ai.insly.com/nora/onboarding/web-app-access-and-roles)            | All        |
| Prod sender whitelist                                                              | [Sender whitelist](https://docs.ai.insly.com/nora/onboarding/sender-whitelist)                            | Email      |
| Prod broker source (Ledger user / mapping) + missing broker (follow-up / fallback) | [Broker mapping](https://docs.ai.insly.com/nora/onboarding/broker-mapping)                                | Email      |
| Own mailbox live and redirecting (if chosen)                                       | [Intake and email address](https://docs.ai.insly.com/nora/onboarding/intake-and-email-address)            | Email      |
| Go-live date and first group of senders                                            | [Testing, go-live and hypercare](https://docs.ai.insly.com/nora/onboarding/testing-go-live-and-hypercare) | All        |


# Skills


# Email intake and Email whitelisting

### Email intake

The simplest way to submit information to Nora is by email. Brokers can send their submissions directly to a dedicated email address, and Nora will automatically extract and structure the data — no login required, no forms to fill out, no learning curve.

This means brokers can continue working the way they always have, while your team benefits from automated processing on the backend.

The submission is instantly available in the Nora UI, where another team member can pick it up and validate it. Email intake also supports workflows where the submitter and the processor are different people. A broker can email in a case, and your internal team handles everything from there.

It's fast, flexible, and removes friction from the submission process.

Email intake is available on all plans and is pre-configured out of the box.

### Email whitelisting

Not everybody should be able to commandeer your time and attention. Nora gives you control over who can submit via email.

You can define which domains or individual email addresses are allowed to send submissions into the system. Only messages from whitelisted senders will be processed — everything else is ignored.

This keeps your intake clean, your workflow focused, and your team protected from spam or irrelevant submissions.

Whitelisting can be configured at the domain level (e.g., all addresses from `@brokerfirm.com`) or for specific individual addresses. You have full flexibility to adjust the list as your broker relationships evolve.

It's a simple safeguard that ensures only trusted partners can access your underwriting pipeline.

{% hint style="info" %}
For information on how to set up this feature, please [reach out to us](https://docs.ai.insly.com). Email whitelisting is available on the M plan and upwards.
{% endhint %}


# Role-based access

Not everyone needs to see everything. FormFlow lets you control exactly what each user can access based on their role.

Internal team members — underwriters, operations staff, managers — can be assigned as full members with complete visibility across all submissions and full control over the platform.

External users, like brokers, can be assigned as viewers. They only see the submissions they've personally sent in. Nothing else. This keeps your pipeline confidential while still giving brokers transparency into the status of their own cases.

This means brokers can check in on their submissions without needing to call or email for updates — and your team doesn't need to worry about exposing sensitive data or competitive intelligence.

Role-based access ensures the right people see the right information, and nothing more.

For information on how to set up roles and permissions, see the configuration guide, or reach out to us. Role-based access is available on the M plan and upwards.

{% hint style="info" %}
For information on how to set up this feature, please [reach out to us](https://docs.ai.insly.com). RBAC is available on the L plan and by custom agreement.
{% endhint %}


# Chat agent integration

FormFlow can meet your users wherever they already are. Our chat agent can be embedded directly into other SaaS platforms, giving brokers or clients a conversational way to submit information without ever leaving the environment they're working in.

The chat agent understands natural language, asks clarifying questions when needed, and processes submissions in real time using FormFlow's extraction engine. The data flows seamlessly into your underwriting pipeline, structured and ready to action.

This makes FormFlow invisible to the end user — they just have a conversation, and the submission gets handled automatically on your side.

#### **Special integration with Insly Ledger**

For users of Insly Ledger, we've built a deeper level of integration. Once a submission is processed and a quote is generated, the agent can navigate the user directly to the quote within the Ledger UI.

The agent can review quote fields in-browser and suggest edits where needed. It can also work with the user to add any additional information to the quote, all through natural conversation.

The result is a completely unified experience — brokers submit, review, and refine quotes without switching tools or waiting for back-and-forth emails.

{% hint style="info" %}
For a demo or information on how to set this up, please [reach out to us](https://docs.ai.insly.com). Agentic experiences are available on L and Enterprise plans, and require an Insurance Copilot licence.
{% endhint %}


# Email Follow Up

One of the biggest bottlenecks for underwriters is chasing brokers for missing information. When a submission arrives without all the required details, underwriters cannot proceed with creating a quote. This creates a back-and-forth “email ping-pong” that can easily waste hours and stall deals.

Nora removes this pain completely.

* If required values are missing after extraction, Nora automatically sends an email to the submitting broker.
* The email includes a clear reference to which fields are missing. The template and wording are fully customizable to match your tone and process.
* The broker simply replies to the email — either itemised or freeform — and the system re-processes the response.
* Missing values are automatically added to the submission, and the underwriter gets a notification that the case is now complete and ready to quote.

All of this happens without the underwriter lifting a finger. The email does not land in their inbox; it goes directly into Nora, where the submission is enriched and marked as complete.

**This feature eliminates:**

* repetitive manual communication,
* speeds up quoting,
* ensures brokers get a faster response.

Underwriters save valuable time, reduce errors, and focus on what really matters: assessing risk and writing more business.

{% hint style="info" %}
For information on how to set up this feature, see the [configuration guide](https://docs.ai.insly.com/nora/configuration-guide/set-up-email-follow-ups), or [reach out to us](https://docs.ai.insly.com). Email follow-ups are available on the **Standard** **plan** and upwards.
{% endhint %}


# Configuration guide

Formflow has first-party integration support for Insly Ledger. The integration allows for:

* manual or automatic export of submissions
* [email follow-up](https://docs.ai.insly.com/nora/configuration-guide/set-up-email-follow-ups) functionality with auto-export
* token sharing and federated authentication for Insly Agents

To configure it, navigate to the settings page and locate the custom integration settings. You will want to add a block with `type: "ledger"` defined, for example:

```json
[
  {
    "type": "ledger",
    "settings": {
      "scope": "auth/tenant",
      "tenant": "tenant",
      "baseUrl": "https://tenant.app.beta.insly.training",
      "clientId": "xxxredactedxxx",
      "clientSecret": "xxxredactedxxxxxxredactedxxx"
    }
  },
  // other integration blocks
]
```


# Setting up webhooks

The [Webhook API](https://docs.ai.insly.com/nora/api-documentation/webhooks) allows you to receive real-time notifications when specific events occur in your FormFlow submissions. By subscribing to webhook events, your application can automatically respond to submission processing milestones without polling.

{% hint style="info" %}
These events cover submissions. [Agentic workflow](https://docs.ai.insly.com/nora/agentic-workflows) runs publish no events of their own. To learn when a run finishes, [poll the run](https://docs.ai.insly.com/nora/agentic-workflows/run-agentic-extraction-via-api#no-webhooks-polling-is-the-way-to-get-results).
{% endhint %}

### Available Event Types

The webhook system supports six event types:

<table><thead><tr><th width="252.2890625">Event</th><th>Triggered When</th></tr></thead><tbody><tr><td><code>extracted</code></td><td>AI extraction of submission data completes successfully</td></tr><tr><td><code>export</code></td><td>Manual export is initiated for a submission</td></tr><tr><td><code>validation-success</code></td><td>Submission validation passes before export</td></tr><tr><td><code>error-export</code></td><td>Triggered when export fails (both automatic and manual exports)</td></tr><tr><td><code>error-processing</code></td><td>Triggered when submission processing/extraction fails</td></tr><tr><td><code>error-pre-processing</code></td><td>Triggered when email submission pre-processing fails</td></tr></tbody></table>

All webhook events share a common payload structure:

```json
{
  "eventId": "123e4567-e89b-12d3-a456-426614174000",
  "eventType": "extracted",
  "timestamp": "2023-10-28T12:00:00.000Z",
  "submissionId": "123e4567-e89b-12d3-a456-426614174001",
  "templateId": 1
}
```

### Webhook Security

When creating a subscription for an event, you will receive a `secret` token which you can use to verify whether the webhook is sent by us and is unchanged.

When we send out webhook events a signature is included in the header. This is created by hashing the payload `secret` before transport. You can use the token to hash the payload on your end using **HMAC-SHA256** (hex-encoding) and compare if the signatures match to confirm that the payload is valid and unchanged.

{% hint style="warning" %}
**Important**: You must use the exact raw request body string to compute the hash, not a re-serialized version of the parsed JSON. Different JSON serialization can produce different strings even for the same data.
{% endhint %}

#### **Signature Headers**

<table><thead><tr><th width="205.23828125">Header</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>X-Webhook-Signature</code></td><td>HMAC-SHA256 signature (hex-encoded)</td><td><code>a3b2c1d4e5f6...</code></td></tr><tr><td><code>X-Webhook-Timestamp</code></td><td>ISO 8601 timestamp when signature was generated</td><td><code>2023-10-28T12:00:00.000Z</code></td></tr></tbody></table>

### Receiving Webhooks

#### Endpoint Requirements

Your webhook endpoint should:

1. **Respond quickly** - Return a 2xx status code within 5 seconds
2. **Be publicly accessible** - The webhook service must be able to reach your endpoint
3. **Handle idempotency** - The same event may be delivered multiple timesx

Below is an example on how verification works.

```javascript
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Here we have a separate endpoint for an event, it is also possible to
// create logic that chooses the correct secret based on the "type" field
app.post('/webhooks/formflow/extracted', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  
  
  const secret = process.env.WEBHOOK_SECRET_EXTRACTED;
  
  if (!signature || !verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process verified webhook...
});
```


# Process a submission via API

This guide explains how to process a submission using the FormFlow API.&#x20;

The sequence involves creating a submission, uploading files, and initiating processing. By the end of the process, the submission will be in the "ready for review" status.

The steps to process a typical submission are as follows:

{% stepper %}
{% step %}

### Create an empty submission

Call [`POST /api/submission`](broken://pages/9759ca3f5fdf53f3395ef66b2964fde0c0e0db92#post-submission) to create an empty submission.

{% endstep %}

{% step %}

### Upload files

Use `POST /api/submission/{id}/upload` to retrieve a secure file upload URL for each file in your submission. `{id}` refers to the submission ID from step 1.

The `contentType` parameter in the request body must be one of the following:

```
application/pdf
application/msword
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/vnd.ms-excel
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
image/jpeg
image/heic

```

`PUT` the files to the URLs. You will need to do multipart uploading for files exceeding 5MB. Only proceed after all files are finished uploading.

{% endstep %}

{% step %}

### Initiate processing

Call [`POST /api/processing`](https://docs.ai.insly.com/nora/api-documentation/processing#post-processing) to initate processing. The response payload will include a unique processing event ID, which you can use in step 4:

```json
{
  "eventId": "string",
  "submissionId": "string",
  "message": "The submission has been queued for processing. You may GET the event status using the provided event ID."
}
```

{% endstep %}

{% step %}

### Check processing status

You can check `GET /api/processing/{id}` to check on the processing event. The response will include a `state` value:

```json
{
  "id": "string",
  "submissionId": "string",
  "type": "extraction",
  "state": "pending",
  "createdAt": "2025-04-07T12:18:24.000Z",
  "updatedAt": "2025-04-07T12:18:24.000Z"
}
```

{% endstep %}

{% step %}

### Retrieve processed submission

Finally, when the processing event is in the `processed`  state, you can `GET /api/submission/{id}` to retrieve the full submission to inspect its `payload`:

```json
{
  "id": "string",
  "submissionNumber": "number",
  "name": "string",
  "template": {
    // Template details
  },
  "templateId": "number",
  "uploaderUserId": "string",
  "userId": "string",
  "files": [
    // List of files
  ],
  "payload": {
    // structed data gathered from files
  }
  "status": "processed",
  "createdAt": "string",
  "updatedAt": "string"
}
```

{% endstep %}
{% endstepper %}


# Create a submission export flow

When a user or automation marks a Formflow submission as "completed", then you likely want to make use of the data somewhere else.&#x20;

It is straightforward to set up a custom export flow. There are a number of helpful third party services for such processing, including [n8n](https://n8n.io/), [Zapier](https://zapier.com/) and [IFTTT](https://ifttt.com/), or you can roll your own solution.&#x20;

All approaches can make use of Formflow's [webhook](https://docs.ai.insly.com/nora/api-documentation/webhooks) notifications, [API](https://docs.ai.insly.com/nora/api-documentation) and MCP services.

### Be notified of new submissions

You will want to react to new submissions in the `completed` status. There are two ways to automate this:

* Regularly poll [`GET /submission`](broken://pages/9759ca3f5fdf53f3395ef66b2964fde0c0e0db92#get-submission) for a list of the most recent submissions, maintain a list of processed submissions, and choose which submissions to process
* Register a [webhook subscription](https://docs.ai.insly.com/nora/api-documentation/webhooks#post-webhook-subscription). In this case, Formflow will `POST` at your designated endpoint and include a submission ID.

### Fetching completed submissions

Regardless of how you became aware of a new completed submission, you will want to [`GET /submission/{id}`](broken://pages/9759ca3f5fdf53f3395ef66b2964fde0c0e0db92#get-submission-id) using the unique submission ID. The response will include:

* submission metadata
* presigned temporary file download URLs (if configured)
* the complete data payload in JSON format

You can then process the submission `payload` per your business logic.&#x20;


# Set up email follow-ups

It is possible to configure Formflow in such a way that the system automatically prompts the submitting user about missing values over email. This is useful in situations where submissions may come from parties who will not be accessing the web UI at all.

In this scenario, a submission will be marked as "completed" automatically when all required fields are present in the extracted payload.

### Submission flow

{% columns %}
{% column %}
If, after extraction, there are required values missing, an email is sent back to the submitting user.&#x20;

A reference to the missing fields will be provided. The user may reply to the email how they like: as an itemised response, or as a freeform reply.&#x20;

The email is re-processed and additional data points are added to the submission.

The submission is marked as `completed` once all required fields are set, and it will be exported to Ledger as a new quote. The user will receive a "success" email.

The email loop will not be triggered if all required values are present immediately: in that case the submission will instantly be marked as completed. This will also happen in case there are no required fields set.
{% endcolumn %}

{% column %}

<figure><img src="https://4110327221-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIl1X3JAZ6wvoa5MKf9ny%2Fuploads%2FLrtiT0LvyR8GG3FucnuK%2F13c6f5d6-db6b-4380-836f-1639aee9b778.png?alt=media&amp;token=62c20ab4-4635-4ab0-b315-0cd540cb5832" alt="" width="375"><figcaption></figcaption></figure>

{% endcolumn %}
{% endcolumns %}

### Configuring follow-ups:

Go to Formflow Settings. Locate the custom configurations section, and add a new property `enableFollowUp` and define it as `true`, for example:

```json
[
  {
    "type": "ledger",
    //
    // other 'settings' omitted...
    //
    "enableFollowUp": true,
    "export-by-default": true
  }
]
```


# Email notifications

FormFlow sends automated email notifications through SendGrid using dynamic templates. There are **4 message categories** that you should create custom templates for:&#x20;

* `SUCCESS`
* `VALIDATION`
* `ERROR`
* `REJECTION`

Each category can have its own SendGrid template with custom branding and styling.&#x20;

In addition to a `message_category`, each message will also have a `message_type`, and you will want to handle different types of messages with in-template logic, as well as define a fallback condition to send a generic email in case you encounter a new type of email in the future.

## Email Notification Types

### Success emails

Positive confirmations as feedback to the user that all is going according to plan.

<details>

<summary>Processing has begun</summary>

If an email is well received, we are able to pull all of its attachments, and all attachments are valid, then we reply to user to say that their submission is being processed.

**Example Payload:**

```json
{
  "subject": "Your Submission is Being Processed",
  "message_category": "SUCCESS",
  "message_type": "submission_started",
  "submission_id": "ab761b6e-c9ba-41ef-9d08-b41c4e1de35b",
  "suggested_message": "Thank you for your submission. We have successfully received your documents and processing has begun. You will be notified once the process is complete.",
  "data": {}
}
```

</details>

<details>

<summary>Submission completed</summary>

If email loopback functionality is enabled, and Ledger integration is configured, and the submission is completed, and it has been successfully exported to Ledger, we inform the user of this.

**Example Payload:**

```json
{
  "subject": "Submission Processed Successfully",
  "message_category": "SUCCESS",
  "message_type": "submission_completed",
  "submission_id": "ab761b6e-c9ba-41ef-9d08-b41c4e1de35b",
  "suggested_message": "Your submission has been successfully processed and exported to our system. Thank you for using FormFlow.",
  "data": {}
}
```

</details>

### Validation emails

Information requests – something about a submission is incomplete and requires the submitting user's attention.

<details>

<summary>Missing fields</summary>

If email loopback functionality is enabled and an extraction is complete, but there are validation errors.

**Example Payload:**

```json
{
  "subject": "Additional Information Required - Submission #12345",
  "message_category": "VALIDATION",
  "message_type": "missing_fields",
  "submission_id": "ab761b6e-c9ba-41ef-9d08-b41c4e1de35b",
  "suggested_message": "Thank you for your submission. We have reviewed your documents and found that some required information is missing or incomplete. Please review the items listed below and resubmit your documents with the necessary details.",
  "data": {
    "missing_fields": [
      "Policy holder's date of birth",
      "Vehicle registration number",
      "Proof of no claims bonus",
      "Current insurance certificate expiration date"
    ]
  }
}
```

</details>

### Rejection emails

Active rejections: something about the submisison is unsatisfactory. It is likely that the user can do something about the situation.

<details>

<summary>Unsupported attachments</summary>

If one or more attachments are not supported, then we advise the user that their submission will not be processed.

**Example Payload:**

```json
{
  "subject": "Submission Not Supported",
  "message_category": "REJECTION",
  "message_type": "unsupported",
  "submission_id": "ab761b6e-c9ba-41ef-9d08-b41c4e1de35b",
  "suggested_message": "Thank you for your submission. Unfortunately, we are unable to process the documents you have submitted as they do not match the required format or document type we currently support.",
  "data": {
    "rejection_reasons": [
      "The submitted documents are in an unsupported file format",
      "Only PDF, PNG, and JPEG files are accepted",
      "Please resubmit your documents in a supported format"
    ]
  }
}
```

</details>

<details>

<summary>Whitelist rejection</summary>

If email whitelisting is configured, and the emailing user is not whitelisted by domain or email address, then we advise the user that their submission is not accepted.

**Example Payload:**

```json
{
  "subject": "Access Restricted",
  "message_category": "REJECTION",
  "message_type": "whitelist",
  "submission_id": "no-submission",
  "suggested_message": "We appreciate your interest. However, access to this service is currently limited to authorized partners and pre-approved organizations.",
  "data": {
    "rejection_reasons": [
      "Your email address or domain is not currently authorized",
      "Please contact your account manager to request access"
    ]
  }
}
```

</details>

### Error emails

Advisory email regarding processing failures. In these cases it is unlikely that the user can do something, and they should probably contact a support channel.

<details>

<summary>Pre-processing error</summary>

If there is an unexpected issue reading the incoming email, then we respond with a generic error message.

**Example Payload:**

```json
{
  "subject": "Error Reading Your Submission",
  "message_category": "ERROR",
  "message_type": "preprocessing",
  "submission_id": "no-submission",
  "suggested_message": "We encountered an issue while reading your email submission. Please try resubmitting your documents, or contact support if the problem persists.",
  "data": {
    "error_messages": [
      "Unable to parse email content",
      "Attachment extraction failed"
    ]
  }
}
```

</details>

<details>

<summary>Processing error</summary>

If there is an issue during processing, then we respond with an error message, detailing the submission ID, failure stage and a short error stack.

**Example Payload:**

```json
{
  "subject": "Submission Processing Failed",
  "message_category": "ERROR",
  "message_type": "processing",
  "submission_id": "ab761b6e-c9ba-41ef-9d08-b41c4e1de35b",
  "suggested_message": "We encountered an issue while processing your submission. Our technical team has been notified and is investigating the problem.",
  "data": {
    "error_messages": [
      "There was a problem during processing, and your documents have not been processed.\n Processing Step: convertFiles.\n Error message: Some error message.\n Submission ID: ab761b6e-c9ba-41ef-9d08-b41c4e1de35b.\n If the issue persists, please contact your Account Manager."
    ]
  }
}
```

</details>

<details>

<summary>Export error</summary>

If Ledger integration is configured, but exporting a submission fails even after it passes validation, then we respond with a generic error message.

**Example Payload:**

```json
{
  "subject": "Export to System Failed",
  "message_category": "ERROR",
  "message_type": "export",
  "submission_id": "ab761b6e-c9ba-41ef-9d08-b41c4e1de35b",
  "suggested_message": "Your submission was processed successfully, but we encountered an issue exporting it to our external system. Our team has been notified and will resolve this shortly.",
  "data": {
    "error_messages": [
      "Export to Ledger failed",
      "Connection timeout to external service",
    ]
  }
}
```

</details>

***

## Setting Up SendGrid Templates

FormFlow uses SendGrid's dynamic templates to send emails. Each template uses Handlebars syntax to dynamically insert data from the payload.

### Template Structure

All email payloads follow a standardized, flattened structure for SendGrid:

```typescript
{
  subject: string;              // Email subject line
  message_category: string;     // SUCCESS, VALIDATION, ERROR, or REJECTION
  message_type: string;         // Specific type within category
  submission_id: string;        // Unique submission identifier
  suggested_message: string;    // Main message body
  data: {                       // Optional additional data
    // Category-specific fields
  }
}
```

### Example: Validation Template Setup

**1. Create the HTML Template in SendGrid:**

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Validation - Missing Information</title>
</head>
<body style="margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif; background-color: #e8e8e8;">
    <table role="presentation" style="width: 100%; border-collapse: collapse;">
        <tr>
            <td align="center" style="padding: 40px 20px;">
                <table role="presentation" style="max-width: 700px; width: 100%; border-collapse: collapse;">
                    <!-- Logo -->
                    <tr>
                        <td style="padding: 0 0 30px 0;">
                            <img src="https://insly.com/wp-content/uploads/2024/06/Logo-with-text-4.png" alt="Insly" style="height: 40px; display: block;">
                        </td>
                    </tr>
                    
                    <!-- Content Card -->
                    <tr>
                        <td style="background-color: #ffffff; border-radius: 8px; padding: 50px 40px; box-shadow: 0 2px 8px rgba(0,0,0,0.08);">
                            <h1 style="margin: 0 0 30px 0; color: #1a1a1a; font-size: 28px; font-weight: 600; line-height: 1.3;">
                                Additional information is required
                            </h1>
                            
                            <!-- Dynamic suggested message -->
                            <p style="margin: 0 0 20px 0; color: #333333; font-size: 18px; line-height: 1.6;">
                                {{suggested_message}}
                            </p>
                            
                            <!-- Conditional missing fields list -->
                            {{#if data.missing_fields}}
                            <p style="margin: 0 0 15px 0; color: #333333; font-size: 18px; line-height: 1.6;">
                                The following fields are missing or incomplete:
                            </p>
                            <ul style="margin: 0 0 20px 0; padding-left: 25px; color: #333333; font-size: 18px; line-height: 1.8;">
                                {{#each data.missing_fields}}
                                <li>{{this}}</li>
                                {{/each}}
                            </ul>
                            {{/if}}
                            
                            <p style="margin: 25px 0 0 0; color: #333333; font-size: 18px; line-height: 1.6;">
                                Please provide the missing information and resubmit your documents.
                            </p>
                        </td>
                    </tr>
                    
                    <!-- Footer -->
                    <tr>
                        <td style="padding: 30px 0 0 0;">
                            <p style="margin: 0 0 10px 0; color: #888888; font-size: 15px; line-height: 1.6;">
                                This automated email was sent by FormFlow, and responses will not be read.
                            </p>
                            <p style="margin: 0; color: #888888; font-size: 15px; line-height: 1.6;">
                                With questions, please reach out to your customer success representative, or to 
                                <a href="mailto:info@insly.com" style="color: #888888; text-decoration: underline;">info@insly.com</a>
                            </p>
                        </td>
                    </tr>
                </table>
            </td>
        </tr>
    </table>
</body>
</html>
```

**2. Understanding Handlebars Syntax:**

* `{{variable}}` - Inserts the value of a variable
* `{{#if condition}}...{{/if}}` - Conditional rendering
* `{{#each array}}...{{/each}}` - Loop through array items
* `{{this}}` - Current item in a loop

**3. Key Template Variables:**

All templates have access to these flattened variables:

* `{{subject}}` - Email subject
* `{{message_category}}` - Category (SUCCESS, VALIDATION, ERROR, REJECTION)
* `{{message_type}}` - Specific message type
* `{{submission_id}}` - Submission identifier
* `{{suggested_message}}` - Main message content
* `{{data}}` - Object containing category-specific fields

**4. Category-Specific Data Fields:**

**Validation emails:**

```handlebars
{{data.missing_fields}} - Array of missing field names
```

**Error emails:**

```handlebars
{{data.error_messages}} - Array of error message strings
```

**Rejection emails:**

```handlebars
{{data.rejection_reasons}} - Array of rejection reason strings
```

**Success emails:**

```handlebars
{{data.confirmation_details}} - Array of confirmation message strings
```

**5. Configure in Organization Settings:**

Inside FormFlow's settings tab editor you can assign the SendGrid template IDs to their respective message categories.  \
\
Here you can see the `templates` object has truncated SendGrid template IDs, you should include yours in full.

```json
{
  "sendgrid": {
    "api_key": "SG.xxxxx",
    "from_email": "noreply@yourcompany.com",
    "from_name": "FormFlow",
    "templates": {
      "validation": "d-abc123...",
      "error": "d-def456...",
      "rejection": "d-ghi789...",
      "success": "d-jkl012...",
      "fallback": "d-mno345..." // this one has to be set
    }
  }
}
```

**6. Testing Your Template:**

Use SendGrid's template editor test feature with this sample data:

```json
{
  "subject": "Test Validation Email",
  "message_category": "VALIDATION",
  "message_type": "missing_fields",
  "submission_id": "test_12345",
  "suggested_message": "This is a test validation message.",
  "data": {
    "missing_fields": [
      "Test Field 1",
      "Test Field 2"
    ]
  }
}
```

### Best Practices

1. **Always provide fallback content** - Use `{{#if}}` blocks to handle missing data gracefully
2. **Keep inline styles** - Email clients have limited CSS support
3. **Test across email clients** - Use services like Litmus or Email on Acid
4. **Use semantic HTML** - Tables for layout (email client compatibility)
5. **Optimize images** - Host externally and use absolute URLs
6. **Keep file size small** - Some email clients truncate large emails


# Insly Ledger integration


# Setting up configuration

{% hint style="info" %}
API crentials can be issued by Ledger support team representatives
{% endhint %}

To set up Ledger integration you will need need to add "ledger" type settings object to an array of settings.

Here is an example of the setting:

```json
[
  {
    "type": "ledger",
    "settings": {
      "env": "environment-in-ledger",
      "scope": "auth/your-tenant-name",
      "tenant": "your-tenant-name",
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "brokerShortName": "your-broker-name" // optional
    }
  },
  // other existing settings here
]
```

Settings description:

| Setting         | Type   | Description                                                                 |
| --------------- | ------ | --------------------------------------------------------------------------- |
| env             | string | enum; can be either "prod", "demo" or "beta"                                |
| scope           | string | scope is always your tenant name with a prefix of "auth/"                   |
| clientId        | string | issued by Ledger                                                            |
| clientSecret    | string | issued by Ledger                                                            |
| brokerShortName | string | optional; set it only if you wish to create quote under one specific broker |


# Import and update templates

If integrated with Insly Ledger, then you will have the ability to import schemas from Ledger into Formflow as templates. The specified schema version will become the export destination.

### Modifications made during import

#### **Unwanted root properties are removed**

There are some pre-defined fields which are not needed for data extraction, and are therefore removed:&#x20;

```
notes
documents
schedules
endorsements
referralComments
underwritingNotes
underwriteNotes
underwriterNotes
referralRules
```

#### `$ref` references are resolved

Any `$ref` pointers are resolved to the actual definition objects. Formflow is RJSF-friendly, but not fully compliant. The Formflow template may therefore include repeated fields.

#### Only required and supported parameters are copied

We copy over only selected fields and recursively process nested `properties` and array `items`:

```
schema.type
schema.title
schema.description
schema.enum
schema.enumNames
schema.minItems
schema.maxItems
schema.format
```

*Note:* `minItems` and `maxItems` are kept for the Formflow template schema but removed before AI extraction.

#### **Dependencies and** `oneOf` **conditions are merged**

For example, if choosing *Option 1* reveals *sub-option 1* and *sub-option 2* in `sectionB`, those values are merged directly into `sectionB`, and the dependencies are discarded.

#### **All enums are combined**

We merge all enum possibilities into a single, unified enum.


# Exporting to Ledger

It is a good idea to test many different submissions in demo → beta to encounter as many validation issues as possible. Formflow does hold a copy of all dependency requirements and does its best to validate all related requirements, but very complex schemas deserve thorough testing.

### "No binder available for quote"

This issue appears if Ledger is unable to assign a binder. This is chosen based on three key pieces of data:

* `broker.shortName` – this is pulled from the payload, and the field must remain in the Formflow template. Make sure it is an enum with allowed values and remember that suitable values may be different between pre-production and production environments.
* `policy.dateInception` – this date field is pulled from the payload. It must exist, be valid, and fall within the start and end dates of a valid binder.
* `schema.name` – this is passed with the template if the Ledger integration is correctly configured, and is unlikley to be the issue.


# Multi-factor authentication

When using Formflow, each user has the ability to set up multi-factor authentication. The accepted method is a TOTP-based authentication application, e.g. 1Password or Google Authenticator.

To set up MFA, navigate to your profile view from the top right hand corners, and open "Security". Look out for "**Two-step verification**": this allows you to go into the MFA setup flow.

<figure><img src="https://4110327221-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIl1X3JAZ6wvoa5MKf9ny%2Fuploads%2FnxvblmU5aC41QXAQfnul%2FScreenshot%202025-11-07%20at%2015.11.25.png?alt=media&amp;token=28d8e275-2383-4559-8f5c-a8c9fe071882" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
As an organisation leader, you may request that MFA is made mandatory across all users in your organisation. Please reach out to your account manager if that is the case.
{% endhint %}


# Set up human spot checks

## Spot Check Sampling

Spot check sampling lets you route a configurable percentage of submissions for manual review before they are exported. This is useful during tenant onboarding when extraction quality needs to be validated, and can be gradually reduced as confidence grows.

### Configuration

Spot checking is configured per tenant in the organization settings. The configuration is a JSON object added to the tenant's `integrations` array.

#### Example

```json
{
  "type": "spot-check",
  "enabled": true,
  "sampleSize": 50,
  "spotCheckerEmails": [
    "reviewer@yourcompany.com",
    "triage-inbox@linear.app"
  ],
  "templateOverrides": [
    { "templateId": 3, "sampleSize": 50 }
  ]
}
```

### How it works

When a submission is fully processed and ready for export, the system rolls a random number against the configured sample rate. If selected:

1. The submission is **not exported** automatically
2. It stays in **"Ready for Spot Check"** status in the dashboard
3. All configured spot checkers receive a **notification email**
4. A reviewer opens the submission, assigns it to themselves, and reviews the extracted data
5. The reviewer clicks **Mark as completed** — this exports the submission, sets the status to **"Completed"**, and sends the end user a **confirmation email**
6. The end user receives a **confirmation email** that their submission was processed

Submissions that are not selected continue through the normal automatic export flow with no change.

#### Settings reference

| Setting                          | Type             | Required              | Description                                                                                                                                                        |
| -------------------------------- | ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`                        | boolean          | Yes                   | Enables or disables spot checking for the tenant. Set to `false` to disable without removing the configuration.                                                    |
| `sampleSize`                     | integer (0-100)  | Yes                   | Percentage of submissions routed to spot check. `0` = no submissions selected (effectively disabled). `100` = every submission is selected.                        |
| `spotCheckerEmails`              | array of strings | Yes                   | Email addresses that receive a notification when a submission is selected. Supports multiple addresses. Can include team inboxes or Linear triage email addresses. |
| `templateOverrides`              | array of objects | No                    | Optional per-template overrides for the sample rate.                                                                                                               |
| `templateOverrides[].templateId` | integer          | Yes (within override) | The ID of the template to override.                                                                                                                                |
| `templateOverrides[].sampleSize` | integer (0-100)  | Yes (within override) | The sample rate for this specific template. Takes precedence over the tenant-level `sampleSize`.                                                                   |

#### Template overrides

You can set different sample rates for different templates. For example, a tenant might need 100% review on a new template while an established one only needs 10%:

```json
{
  "sampleSize": 10,
  "templateOverrides": [
    { "templateId": 7, "sampleSize": 100 }
  ]
}
```

In this example, template 7 has every submission reviewed, while all other templates are sampled at 10%.

### Enabling spot checking for a tenant

To enable spot checking for your tenant, contact the Nora team with:

* The **email addresses** that should receive spot check notifications
* The desired **sample size**
* Any **per-template overrides** if needed

> **Tip:** Start with `sampleSize: 100` during initial onboarding so every submission is reviewed. Reduce gradually as extraction quality is validated (e.g. 100 → 50 → 10 → 0).

### Disabling spot checking

Either set `enabled` to `false` or set `sampleSize` to `0`. Both stop new submissions from being selected, but existing spot check candidates in the queue are not affected.

### Reviewer workflow

#### 1. Receive notification

When a submission is selected for spot check, each email address in `spotCheckerEmails` receives an email with the submission name and number.

#### 2. Open the submission

In the FormFlow dashboard, spot-checked submissions are displayed with an orange **"Ready for Spot Check"** status badge, making them easy to identify in the submissions list.

#### 3. Assign and review

Open the submission and assign it to yourself. The status changes to **"In Spot Check"**. Review the extracted data against the source documents to verify accuracy.

#### 4. Complete the review

When satisfied with the data, click **Mark as completed**. This exports the submission, delivers a confirmation email to the end user, and sets the status to **"Completed"**.

### End user experience

The end user (the person who submitted the original documents) is not aware that their submission was selected for spot check. From their perspective:

* They submit documents as usual
* They receive the same confirmation email they would normally receive
* The only difference is a potential delay while the reviewer checks the data

### Recommended ramp-down schedule

| Phase               | sampleSize | When                                 |
| ------------------- | ---------- | ------------------------------------ |
| Initial onboarding  | 100        | First 1-2 weeks — review everything  |
| Building confidence | 50         | Weeks 2-4 — spot check half          |
| Monitoring          | 10-20      | Ongoing — periodic quality checks    |
| Fully automated     | 0          | When confident in extraction quality |

Adjust timelines based on submission volume and error rates observed during review.


# Writing AI hints

## What it is

Every field in a template can take an optional **AI hint**: a short instruction the AI reads when it extracts that field. Use it to tell the AI how to map what the broker sent to the field, when the field title alone is not enough.

Many fields need no hint. The template structure and field titles are often descriptive enough (e.g. **Applicant > First name**). Add a hint where testing shows the AI getting a field wrong, or where you already know the source is ambiguous.

## What makes a good hint

* **Short and direct.** One or two sentences about this one field.
* **Examples.** Show the input and the expected result: `"AB12 CDE" → "AB12CDE"`. Examples work better than descriptions.
* **Say what to do when the answer is missing.** Leave it empty, or derive it from somewhere else. Without that, the AI may guess.
* **Name the trap.** If there is a similar value it tends to pick instead, say which one not to use.

## Examples by type

### Format / normalise

* **Registration number:** Return it with all spaces removed. Keep every other character exactly as written. Examples: "AB12 CDE" → "AB12CDE"; "A123 BCD" → "A123BCD".
* **Date of birth:** In YYYY-MM-DD. Examples: "16/11/1963" → "1963-11-16"; "2 January 2002" → "2002-01-02".
* **UK phone number:** Keep the leading 0 (e.g. 07123 456789), never drop it.

### Infer / derive

* **Applicant > Country of residence:** If this is not stated in the source document, infer it from the correspondence address.
* **Gross vehicle weight in tonnes:** The source column is in kg, so divide by 1000. Example: 3500 → 3.5.

### Locate: where in the document to look

* **Number of seats:** Found under "Number of seats" / "Seating capacity", usually in the vehicle's Additional Details section. Extract only when stated; do not infer it from body type.

### Default / when to leave empty

* **Modified?:** Answer "Yes" or "No" only if the document has a modifications question and answers it. If modifications aren't mentioned, leave it empty. Do NOT default to "No".

### Disambiguate: don't confuse with a similar value

* **Policy start date:** When the NEW quoted cover begins. A broker's "Renewal date 15/03/27" is the START of the new cover. Never use the email date, document date or the previous policy's expiry.

### Split one source value into two fields

* **Model:** The base model name only. Everything after it goes in Trim. Examples: "DEFENDER 110 HSE HARD TOP D250" → model "DEFENDER 110", trim "HSE HARD TOP D250"; "FABIA 2" → model "FABIA", trim "2". Never repeat words across model and trim.

## Check the result

After adding or changing a hint, rerun a sample submission that had the problem and check the field. See [Sample submissions and golden records](https://docs.ai.insly.com/nora/onboarding/sample-submissions-and-golden-records).


# Agentic workflows

Agentic workflows are a second way to run work in Nora, next to classic submission processing. A request comes in by email, chat or API. Nora picks the right **workflow** and runs its **agents** one after another, then replies on the channel the request came in on.

The first workflow built this way is [agentic extraction](https://docs.ai.insly.com/nora/agentic-workflows/agentic-extraction). It reads documents into a submission, checks it, asks the sender for anything missing, and exports to Insly Ledger. These are the same steps as classic processing, run as separate agents.

{% hint style="info" %}
Classic submission processing, described in [Process a submission via API](https://docs.ai.insly.com/nora/configuration-guide/process-a-submission-via-api) and the [API documentation](https://docs.ai.insly.com/nora/api-documentation), is unchanged and still supported. Agentic workflows use their own email addresses and endpoints, separate from classic processing.
{% endhint %}

### Key terms

<table><thead><tr><th width="180">Term</th><th>What it means</th></tr></thead><tbody><tr><td><strong>Agent</strong></td><td>An HTTP service that does one job, such as extracting data or exporting to Ledger. Nora calls it with a standard request and reads back a standard result. An agent can be hosted by Nora or by you (for example, an n8n workflow).</td></tr><tr><td><strong>Workflow</strong></td><td>An ordered list of agent steps, plus a plain-language description of the requests it handles.</td></tr><tr><td><strong>Run</strong></td><td>One execution of a workflow. Its status is <code>pending</code>, <code>gathering_params</code> (waiting for the sender to supply something), <code>running</code>, <code>completed</code> or <code>failed</code>. It also records which step it is on.</td></tr><tr><td><strong>Parameters</strong></td><td>The inputs a run needs, such as the template to use or the documents to read. Nora asks the sender for anything missing. Steps can also pass values on to later steps, such as the <code>submissionId</code>.</td></tr><tr><td><strong>Conversation</strong></td><td>The messages and files a run belongs to. In the API it is called a thread (<code>threadId</code>). Agents read documents from it.</td></tr></tbody></table>

### How a request becomes a run

1. **Arrives.** The message and its files are stored on a conversation.
2. **Routing.** Nora decides what the message is. It may be a reply to a question Nora asked, a request for a named workflow, or a new request that Nora matches to the best workflow by its description. Small talk such as "thanks!" gets a short reply and starts nothing.
3. **Gathering.** If the request is missing a parameter, Nora asks for it and waits for the answer. This does not happen on the API, where everything is stated up front.
4. **Steps.** Agents run strictly in order, and each step gets the previous step's output. A step that fails stops the run. An optional step is the exception: if it reports a failure, the run carries on without it.
5. **Answer.** The last step's message is sent back on the same channel: an email reply, a chat message, or the result of an API poll.

### Ways to start a workflow

* [**Start a workflow by email**](https://docs.ai.insly.com/nora/agentic-workflows/start-a-workflow-by-email): send to your organisation's workflow address (`yourcompany+studio@…`).
* [**Run agentic extraction via API**](https://docs.ai.insly.com/nora/agentic-workflows/run-agentic-extraction-via-api): upload files, start a run and poll it for the result.
* **Chat:** a conversation in the Nora web app.

### Getting results out

Agentic workflows have no webhook events you can subscribe to. To get a run's result, poll it, as described in [Run agentic extraction via API](https://docs.ai.insly.com/nora/agentic-workflows/run-agentic-extraction-via-api#no-webhooks-polling-is-the-way-to-get-results).

### Building your own agents

A workflow step can be an agent you host. If you are building one, see [Build an agent](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent). That section is written for agent developers. API clients don't need it.

{% hint style="info" %}
Workflows and agents are set up for your organisation by Insly. To enable agentic workflows or register an agent, [reach out to us](https://docs.ai.insly.com).
{% endhint %}


# Agentic extraction

Agentic extraction takes documents in, turns them into a checked submission, and exports it to Insly Ledger. Along the way it asks the sender for anything that is missing. It does the same work as [classic submission processing](https://docs.ai.insly.com/nora/configuration-guide/process-a-submission-via-api): the same templates, the same extraction, the same validation and the same Ledger export. The difference is that each stage is a separate agent in a workflow. That makes the workflow flexible: Insly can add steps, for example an agent that enriches the data from another source, or remove steps your process doesn't need.

### The steps

Every step after the first needs only the `submissionId`, which the first step creates and passes on.

<table><thead><tr><th width="150">Step</th><th width="210">Needs</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Conversion</strong></td><td><code>templateName</code>, <code>files</code></td><td>Creates a submission from the run's documents against the chosen template and converts the files for processing. Passes <code>submissionId</code> to every later step.</td></tr><tr><td><strong>Extraction</strong></td><td><code>submissionId</code></td><td>Reads the documents into the submission's payload. On a <a href="https://docs.ai.insly.com/nora/agentic-workflows/agentic-extraction#the-follow-up-loop">follow-up run</a> it applies the sender's reply as an edit instead.</td></tr><tr><td><strong>Grounding (fact check)</strong></td><td><code>submissionId</code></td><td>Checks each extracted value against the documents and removes values it cannot support, using your organisation's grounding threshold. Skipped when the threshold is 0.</td></tr><tr><td><strong>Reference</strong> <em>(optional)</em></td><td><code>submissionId</code></td><td>Records where in the documents each value came from.</td></tr><tr><td><strong>Metadata</strong> <em>(optional)</em></td><td><code>submissionId</code></td><td>Names the submission and gives its files readable names.</td></tr><tr><td><strong>Validation</strong></td><td><code>submissionId</code></td><td>Checks the payload against the template and the export rules. If it doesn't pass, for example because a required field is missing, the run <strong>stops here as completed</strong> (see below).</td></tr><tr><td><strong>Export</strong></td><td><code>submissionId</code></td><td>Exports the submission to Insly Ledger using your organisation's Ledger integration, under the same rules as classic processing (see <a href="https://docs.ai.insly.com/nora/agentic-workflows/agentic-extraction#when-export-is-skipped">below</a>).</td></tr></tbody></table>

If an **optional** step reports a failure, the run carries on without that step's result.

The table above shows the standard extraction workflow. Your organisation's workflow may have more steps or fewer.

### Where the inputs come from

* **`templateName`**: on email and chat, the sender names the template, by its name or its email alias. Insly can also fix the template on the workflow, so that the sender never has to name it. On the API, you pass a `templateId`.
* **`files`**: always the documents actually on the conversation, never the message text. If the sender says "quote attached" but nothing is attached, Nora asks for the documents.

### When validation stops the run

If the submission doesn't pass validation, the run ends with status `completed` and export does not run. This is a normal result: the submission isn't ready yet. What happens next depends on the channel:

* **Email:** Nora sends the sender the missing-fields email, the same one classic processing sends. The sender's reply starts the follow-up loop below.
* **Chat:** the reply lists what is missing. The sender's next message starts the follow-up loop.
* **API:** the poll result lists the fields in `missingFields`. See [Run agentic extraction via API](https://docs.ai.insly.com/nora/agentic-workflows/run-agentic-extraction-via-api#missing-fields-over-the-api).

You can also complete the submission by hand in the Nora web app and export it from there. If the sender replies later, the next validation includes your edits.

### When export is skipped

The export step uses the rules of classic processing. The run still ends as `completed`, and its reply says the submission was not exported, when:

* the submission was picked for a [human spot check](https://docs.ai.insly.com/nora/configuration-guide/set-up-human-spot-checks) and is held for review,
* it fails the final export checks,
* email follow-ups are not enabled for your organisation, or it has no Ledger integration,
* the submission has no email sender. **This applies to every run started over the API or in chat.** Only runs started by email are exported automatically. Export the others from the web app or with the [Submissions API](https://docs.ai.insly.com/nora/api-documentation/submissions).

### The follow-up loop

When the sender answers a missing-fields question, the original run is not resumed. Nora starts a **new run** of the same workflow for the same submission, with the sender's reply as input.

1. **Conversion** does not create a new submission. It reuses the existing one and adds any new documents the reply brought.
2. **Extraction** treats the reply as an edit. It works out whether the sender is adding, changing or removing values, then applies only those changes. The submission is not extracted again from scratch. Nora knows which fields it asked about, so a reply like "SO16 0AS" goes to the postal code that was asked for.
3. **Grounding, Reference and Metadata are skipped.** Re-checking an edit could remove a value the sender has just supplied.
4. **Validation** runs again. If the submission now passes, **Export** follows. If not, Nora asks again and the loop repeats.

Each round is a separate run, linked to the one before it. In the Nora web app you see one conversation with all of its rounds.

{% hint style="info" %}
If the sender writes in the same conversation while a run is still working, Nora does not start a second run on top of it.

* **Email:** Nora confirms receipt and uses the message once the current run finishes. If the run ended with a missing-fields email, the message counts as the answer to it.
* **Chat:** Nora asks the sender to wait for its reply and to include any additions in the answer to it.
  {% endhint %}

Related: [Email Follow Up](https://docs.ai.insly.com/nora/skills/email-follow-up), [Fields + required/optional](https://docs.ai.insly.com/nora/onboarding/fields-+-required-optional)


# Start a workflow by email

Every organisation with agentic workflows has its own workflow email addresses. They sit next to the [product addresses](https://docs.ai.insly.com/nora/onboarding/intake-and-email-address) used for classic processing and don't replace them.

### The two address forms

<table><thead><tr><th width="320">Address</th><th>What happens</th></tr></thead><tbody><tr><td><code>{orgSlug}+studio@formflow-email.net</code></td><td>Nora reads the message and picks the workflow that best matches it. If more than one could fit, Nora replies with a short numbered list to choose from.</td></tr><tr><td><code>{orgSlug}+studio-{alias}@formflow-email.net</code></td><td>The message always goes to the workflow with that email alias. Nora doesn't try to work out which workflow is meant.</td></tr></tbody></table>

`{orgSlug}` is your organisation's short name, the same one used in your product addresses. `studio` is a fixed part of the address, so type it as shown. Workflow aliases use lower-case letters, digits and hyphens, for example `yourcompany+studio-motor-quote@formflow-email.net`. Insly sets the alias when it sets up the workflow.

{% hint style="info" %}
If an alias doesn't match any active workflow, the message is not lost. Nora falls back to picking a workflow, as with the plain `+studio@` address.
{% endhint %}

### What happens to a message

* **Small talk is answered, not run.** A "thanks!" gets a short reply and starts nothing, even on an alias address. The address chooses *which* workflow runs, not *whether* the message is a request.
* **Attachments count.** An email whose body is a single covering line, with the documents attached, is read as a request.
* **Missing parameters are asked for.** If the template or the documents are missing, Nora replies and asks for them. The sender answers by replying to that email.
* **Replies continue the conversation.** A reply to Nora's question, to a numbered list, or to a missing-fields email is treated as the answer to it. A reply does not start a new request. See [the follow-up loop](https://docs.ai.insly.com/nora/agentic-workflows/agentic-extraction#the-follow-up-loop).
* **One run per conversation.** A reply sent while that conversation's run is still working doesn't start a second run. Nora confirms receipt and uses the message once the current run has finished. A new email, which is not a reply, starts its own conversation.

The final reply comes from Nora, under your assistant's name. If the workflow produced documents, they are attached to it.

### Good to know

* The [sender whitelist](https://docs.ai.insly.com/nora/onboarding/sender-whitelist) applies to product addresses only. It does not filter messages sent to `+studio` addresses.
* Don't give a product address an alias that starts with `studio`. Messages sent to it would be treated as workflow requests.

Related: [Intake and email address](https://docs.ai.insly.com/nora/onboarding/intake-and-email-address)


# Run agentic extraction via API

Use this to run [agentic extraction](https://docs.ai.insly.com/nora/agentic-workflows/agentic-extraction) from your own system without email: upload the documents, start a run, poll it until it finishes, then read the submission it created.

All requests go to `https://main.formflow-dev.net` and use the same Bearer token as the rest of the API (see [Authentication and limits](https://docs.ai.insly.com/nora/api-documentation/authentication-and-limits)). Your API client token already has access to these endpoints. They are not yet listed in the API reference.

{% hint style="info" %}
These endpoints only start **agentic** runs. To process a submission the classic way, follow [Process a submission via API](https://docs.ai.insly.com/nora/configuration-guide/process-a-submission-via-api).
{% endhint %}

{% hint style="warning" %}
**Runs started over the API are not exported to Ledger automatically.** Automatic export needs an email sender to notify, and an API run has none. When a run has finished, export the submission yourself (see [Read the result](https://docs.ai.insly.com/nora/agentic-workflows/run-agentic-extraction-via-api#read-the-result)).
{% endhint %}

{% stepper %}
{% step %}

### Request upload URLs

`POST /api/studio/uploads`

List every file you are going to upload, with its exact size in bytes. You can list up to 20 files.

```json
{
  "files": [
    { "filename": "proposal-form.pdf", "size": 284113 },
    { "filename": "claims-history.xlsx", "size": 40211 }
  ]
}
```

Leave out `threadId` to start a new conversation, which is what you normally want. To add files to a conversation you started earlier through the API, pass its `threadId`.

**201 response**

```json
{
  "threadId": "5f0c3a6e-2b1d-4f7a-9c3e-0d8b6a1e4f21",
  "files": [
    {
      "fileId": "a1c2e3f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
      "filename": "proposal-form.pdf",
      "mimeType": "application/pdf",
      "size": 284113,
      "uploadUrl": "https://…s3…amazonaws.com/…",
      "method": "PUT",
      "headers": { "Content-Type": "application/pdf", "Content-Length": "284113" },
      "expiresIn": 900
    }
  ]
}
```

Keep `threadId` and every `fileId`. You need them to start the run.

* The file type comes from the filename extension. Allowed: `pdf`, `doc`, `docx`, `xls`, `xlsx`, `csv`, `jpg`, `jpeg`, `png`, `gif`, `heic`.
* Each file can be up to 30 MB.
* If any one file is rejected, the whole request fails with `400`, and nothing is created. A `threadId` that is unknown returns `404`. One that was not created through the API returns `400`.
  {% endstep %}

{% step %}

### Upload the bytes

`PUT` each file's bytes to its `uploadUrl` within `expiresIn` seconds (15 minutes). Send every header listed in `headers`, with exactly those values. The body must be exactly `size` bytes, because the URL is signed for that type and length. Anything else is rejected by storage.

```bash
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @proposal-form.pdf
```

`curl` sets `Content-Length` from the file itself. This request goes straight to storage, so do not send your Bearer token with it.
{% endstep %}

{% step %}

### Confirm each upload

`POST /api/studio/uploads/{fileId}/complete`

No request body. Call this once per file after its `PUT` has succeeded.

**200 response**

```json
{ "fileId": "a1c2e3f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b", "status": "completed", "size": 284113 }
```

`409` means the file has not reached storage. If the `PUT` is still in progress, retry the call when it has finished. If the upload URL expired first, it can't be reused: request a new upload (step 1), which gives a new `fileId`, and upload to that. A file that hasn't been confirmed can't be used in a run.
{% endstep %}

{% step %}

### Start the run

`POST /api/studio/extraction-runs`

```json
{
  "threadId": "5f0c3a6e-2b1d-4f7a-9c3e-0d8b6a1e4f21",
  "fileIds": ["a1c2e3f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b", "b2d3f4a5-6c7e-4f8a-9b0c-1d2e3f4a5b6c"],
  "templateId": 7
}
```

<table><thead><tr><th width="150">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>threadId</code></td><td>Required. The <code>threadId</code> from step 1.</td></tr><tr><td><code>fileIds</code></td><td>Required, 1–20. Confirmed uploads on that conversation. You can name some of its files rather than all of them.</td></tr><tr><td><code>templateId</code></td><td>Required. The template to extract against. See <a href="https://docs.ai.insly.com/nora/api-documentation/templates">Templates</a>.</td></tr><tr><td><code>workflowId</code></td><td>Optional. Only needed if your organisation has more than one active workflow that starts from documents. The error message tells you when it is needed.</td></tr></tbody></table>

**202 response**

```json
{
  "runId": "9e8d7c6b-5a49-4382-8170-6f5e4d3c2b1a",
  "workflowId": "c0ffee00-1234-4abc-9def-0123456789ab",
  "threadId": "5f0c3a6e-2b1d-4f7a-9c3e-0d8b6a1e4f21",
  "status": "running",
  "fileIds": ["a1c2e3f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b", "b2d3f4a5-6c7e-4f8a-9b0c-1d2e3f4a5b6c"]
}
```

The run starts straight away. Over the API nothing is ever asked: if the workflow needs something this request doesn't give, the request fails with `400` and says what is missing.

<table><thead><tr><th width="90">Status</th><th>When</th></tr></thead><tbody><tr><td><code>400</code></td><td><ul><li>One or more <code>fileIds</code> aren't confirmed uploads on that conversation. The whole request is refused, so no run reads only some of your files.</li><li>The conversation was not created through the API.</li><li>Several workflows could run and <code>workflowId</code> is missing.</li><li>The named workflow is inactive or not fully set up.</li><li>The workflow needs a parameter this request can't supply. The message lists it.</li></ul></td></tr><tr><td><code>404</code></td><td>Unknown thread, template or workflow. Or your organisation has no active workflow that starts from documents.</td></tr></tbody></table>
{% endstep %}

{% step %}

### Poll the run

`GET /api/studio/extraction-runs/{runId}`

Poll until `finished` is `true`. A run usually takes a few minutes, so polling every 15–30 seconds is enough.

**200 response, while running**

```json
{
  "runId": "9e8d7c6b-5a49-4382-8170-6f5e4d3c2b1a",
  "status": "running",
  "finished": false,
  "currentStepIndex": 2,
  "stepsTotal": 7,
  "submissionId": "3b7f0a1e-9c2d-4e5f-8a6b-7c8d9e0f1a2b",
  "completedAt": null
}
```

**200 response, finished**

```json
{
  "runId": "9e8d7c6b-5a49-4382-8170-6f5e4d3c2b1a",
  "status": "completed",
  "finished": true,
  "currentStepIndex": 7,
  "stepsTotal": 7,
  "submissionId": "3b7f0a1e-9c2d-4e5f-8a6b-7c8d9e0f1a2b",
  "message": "Your submission has been processed, but it was not exported to the ledger.",
  "completedAt": "2026-10-07T09:41:12.000Z"
}
```

<table><thead><tr><th width="170">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td><code>pending</code>, <code>running</code>, <code>completed</code> or <code>failed</code>.</td></tr><tr><td><code>finished</code></td><td><code>true</code> once the run is <code>completed</code> or <code>failed</code>. Stop polling when it is.</td></tr><tr><td><code>currentStepIndex</code></td><td>Progress only, counted from 0. On a completed run it equals <code>stepsTotal</code>, even when validation stopped the run early. On a failed run it stays at the step that failed. Use <code>finished</code> to tell whether the run is done.</td></tr><tr><td><code>stepsTotal</code></td><td>Number of steps in the workflow.</td></tr><tr><td><code>submissionId</code></td><td>The submission the run created. Appears once the first step has run.</td></tr><tr><td><code>missingFields</code></td><td>Only when validation stopped the run. A readable list of what is missing or invalid.</td></tr><tr><td><code>message</code></td><td>The run's final message. On a failed run, a short technical reason, for example which step failed or timed out.</td></tr><tr><td><code>completedAt</code></td><td>When the run finished, or <code>null</code>.</td></tr></tbody></table>
{% endstep %}

{% step %}

### Read the result

The poll result tells you how the run went. The extracted data is on the submission. Fetch it with [`GET /api/submission/{submissionId}`](https://docs.ai.insly.com/nora/api-documentation/submissions) and read its `payload`, as in classic processing. To check the outcome in code, read the submission's `status`. Don't parse `message`, whose wording can change.

<table><thead><tr><th width="280">Poll result</th><th>Meaning and what to do</th></tr></thead><tbody><tr><td><code>completed</code>, no <code>missingFields</code></td><td>The run went through, but the submission was not exported, because API runs never export automatically. Check the submission's <code>status</code>. If it is held for review, it waits for a reviewer. Otherwise check it with <code>GET /api/submission/{submissionId}/validate</code>, then export it with <code>POST /api/submission/{submissionId}/export</code> or from the web app.</td></tr><tr><td><code>completed</code> with <code>missingFields</code></td><td>The submission was extracted, but it does not pass validation yet. See <a href="https://docs.ai.insly.com/nora/agentic-workflows/run-agentic-extraction-via-api#missing-fields-over-the-api">Missing fields over the API</a>.</td></tr><tr><td><code>failed</code></td><td>A step failed, and <code>message</code> says which. <code>submissionId</code> is there if the submission was created before the failure.</td></tr></tbody></table>
{% endstep %}
{% endstepper %}

### No webhooks: polling is the way to get results

{% hint style="warning" %}
There is no webhook or callback for agentic runs. You can't register a URL to be told when a run finishes, and no run events are published. Polling `GET /api/studio/extraction-runs/{runId}` is how you get the result.
{% endhint %}

The [submission webhooks](https://docs.ai.insly.com/nora/configuration-guide/setting-up-webhooks) may fire for the submission a run creates, for example `extracted`. Use them to follow the submission. They never tell you whether the run finished, failed or stopped for missing fields.

### Missing fields over the API

Over email, Nora asks the sender for missing fields. Over the API there is nobody to ask. The run stops, returns the list in `missingFields`, and leaves the submission in Nora without exporting it. To finish it:

1. Add the missing values in the Nora web app, or with [`PATCH /api/submission/{submissionId}`](https://docs.ai.insly.com/nora/api-documentation/submissions).
2. Check it with [`GET /api/submission/{submissionId}/validate`](https://docs.ai.insly.com/nora/api-documentation/submissions).
3. Export it from the web app, or with [`POST /api/submission/{submissionId}/export`](https://docs.ai.insly.com/nora/api-documentation/submissions).

{% hint style="warning" %}
Don't call `POST /api/studio/extraction-runs` again for the same documents. Every API run creates a **new** submission, so you would end up with a duplicate instead of a completed original.
{% endhint %}


# Build an agent

This section is for **developers building an agent** that runs as a step in a Nora [agentic workflow](https://docs.ai.insly.com/nora/agentic-workflows), for example an n8n workflow or your own service. If you only want to start runs and read results, see [Run agentic extraction via API](https://docs.ai.insly.com/nora/agentic-workflows/run-agentic-extraction-via-api) instead.

An agent is an HTTPS endpoint. For each step, Nora sends it one JSON request (the **envelope**) and reads back one result (the **completion**). Nora treats every agent the same way, whether Nora hosts it or you do.

### The envelope

For each step, Nora sends `POST <your webhook URL>` with `Content-Type: application/json`:

```json
{
  "workflowRunId": "1d2e3f4a-…",
  "agentRunId": "7b8c9d0e-…",
  "threadId": "5f0c3a6e-…",
  "messages": [
    { "role": "user", "content": "Please quote the attached fleet, renewal from 1 November." }
  ],
  "attachments": [
    { "fileId": "a1c2e3f4-…", "name": "fleet-schedule.xlsx", "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "size": 40211, "source": "thread" }
  ],
  "authToken": null,
  "schema": null,
  "workflowParams": { "submissionId": "3b7f0a1e-…" },
  "previousPayload": { "submissionId": "3b7f0a1e-…" },
  "assistant": {
    "name": "Nora",
    "descriptor": "Insly's AI assistant",
    "tone": "friendly/casual",
    "styleNotes": null,
    "instructions": "…"
  },
  "callbackToken": "eyJhbGciOiJIUzI1NiIs…"
}
```

<table><thead><tr><th width="170">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>agentRunId</code></td><td>This step's id. Return it in your completion.</td></tr><tr><td><code>workflowRunId</code>, <code>threadId</code></td><td>The run and the conversation this step belongs to.</td></tr><tr><td><code>messages</code></td><td>The conversation so far, oldest first, ending with the message that triggered the run. At most 30 messages. <code>role</code> is <code>user</code> for the sender and <code>system</code> for Nora.</td></tr><tr><td><code>attachments</code></td><td>The conversation's documents, as ids only, never as bytes or URLs. Download them with <a href="https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent/agent-endpoints#download-a-file">the file endpoint</a>.</td></tr><tr><td><code>workflowParams</code></td><td>The run's parameters: what was gathered from the sender, what is pinned for this step, and what earlier steps produced (see <a href="https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent#declaring-what-your-agent-needs">configuration</a>).</td></tr><tr><td><code>previousPayload</code></td><td>The previous step's <code>outputPayload</code>. <code>null</code> on the first step.</td></tr><tr><td><code>authToken</code></td><td>Your organisation's token for this agent, if your agent's settings declare one. Otherwise <code>null</code>.</td></tr><tr><td><code>schema</code></td><td>The JSON Schema stored in your agent's settings, if any, forwarded as is. Useful for an agent that extracts data against a schema. Otherwise <code>null</code>.</td></tr><tr><td><code>assistant</code></td><td>Your organisation's assistant name and tone. If your agent writes text for the customer, paste <code>assistant.instructions</code> into your system prompt, so your messages sound like Nora's own replies.</td></tr><tr><td><code>callbackToken</code></td><td>A credential for this step only. Use it as <code>Authorization: Bearer</code> on the <a href="https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent/agent-endpoints">agent endpoints</a>. It is valid for your agent's configured timeout.</td></tr></tbody></table>

{% hint style="warning" %}
Treat everything in `workflowParams` and `messages` as untrusted input. Values come from the sender's messages, from your organisation's configuration, and from other agents' output.
{% endhint %}

### Answering: right away, or later

Answer with any `2xx`. Nora reads the response body and decides which of these two cases applies.

**Answer right away.** If the body is a completion, the step finishes straight away:

```json
{
  "type": "completion",
  "agentRunId": "7b8c9d0e-…",
  "isComplete": true,
  "outputPayload": { "quoteReference": "Q-10442" },
  "outputMessage": "Your quote Q-10442 is ready."
}
```

A body counts as a completion only if it has `type: "completion"`, a string `agentRunId`, a boolean `isComplete` and a string `outputMessage`. `outputPayload` is an optional JSON object.

**Answer later.** Any other `2xx` body, including an empty one or `"OK"`, counts as an **acknowledgement**. The step waits until you send the same completion JSON to the [callback endpoint](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent/agent-endpoints#send-a-completion-or-progress-update). Use this for anything that takes longer than a few seconds.

{% hint style="info" %}
A completion with a typo (for example, a missing `outputMessage`) also counts as an acknowledgement. The step then waits until it times out. If a step seems to hang, check the body first.
{% endhint %}

You must answer, or call back, within your agent's **timeout**. After that the step fails with a "took too long" message, and the whole run fails, even if the step is optional. A non-`2xx` response, or a connection error, fails the step with a generic error message.

### Outcomes

<table><thead><tr><th width="230">You send</th><th>What happens</th></tr></thead><tbody><tr><td><code>isComplete: true</code></td><td>The step succeeded. <code>outputPayload</code> becomes the next step's <code>previousPayload</code>. On the last step, <code>outputMessage</code> is the reply the customer receives.</td></tr><tr><td><code>isComplete: false</code></td><td>The step failed. The run stops here, later steps don't run, and the customer receives an error reply based on <code>outputMessage</code>. If the step is marked optional, the run carries on without it.</td></tr><tr><td><code>isComplete: true</code> with <code>outputPayload.haltWorkflow: true</code></td><td>The run stops here with status <strong>completed</strong>, not failed, and <code>outputMessage</code> is the reply. Use this when stopping early is a normal result. Nora's validation step uses it for "required fields are missing".</td></tr></tbody></table>

Write `outputMessage` for the customer. Nora may adjust the wording to match your organisation's tone and the conversation, but keeps the content.

### Declaring what your agent needs

Each agent is registered with two declarations. Insly stores them when it registers your agent.

**Settings** are fixed per organisation when the agent is installed: credentials, a tenant URL and similar. The agent's **settings schema** (`settings_schema`) is a JSON Schema (draft-07), and the organisation's `settings` must match it. Nora checks this when the workflow is set up and again before every call. If the check fails, the step fails with a "not set up correctly" message and your agent is not called.

* Declare an `authToken` property if you want a per-organisation token. Nora sends it as `authToken` in the envelope, and only if you declare it.
* Declare a `ledger` property if your agent works with the organisation's Insly Ledger. Nora then adds `tenantId`, `ledgerBaseUrl` and `role` to `workflowParams`.
* An agent that needs no settings declares none.

**Configuration (`configuration`)** describes each run: what the agent needs and what it gives to later steps.

```json
{
  "parameters": {
    "type": "object",
    "properties": {
      "submissionId": { "type": "string", "description": "Submission to quote" },
      "inceptionDate": { "type": "string", "format": "date", "description": "Policy start date" }
    },
    "required": ["submissionId", "inceptionDate"]
  },
  "produces": ["quoteReference"]
}
```

* **`parameters`** is a JSON Schema for what your agent reads from `workflowParams`. Before the first step runs, Nora asks the sender for every required parameter that nothing else supplies. On the API nothing is asked; the start request fails with `400` instead. The `description` appears in the question sent to the sender, so write it for the customer.
* **`produces`** lists the keys of your `outputPayload` that later steps may use. After your step completes, Nora copies those keys into `workflowParams` for every later step. This is how `submissionId` gets from the conversion step to every later one.

A workflow asks the sender only for what is actually missing. That is every step's required parameters, minus anything an earlier step produces and anything pinned on the step.

**Pinned inputs.** A workflow can set a fixed value for a parameter on one step (`inputs`), for example `{ "productCode": "MOTOR-FLEET" }`. The pinned value goes to that step only and is never asked for. `tenantId`, `ledgerBaseUrl` and `role` are reserved for Nora and can't be pinned.

### Registering an agent

There is no self-service API for registering agents yet. To register one, send Insly:

* the webhook URL (HTTPS, reachable from the internet),
* a timeout in seconds. This is how long you may take to answer or call back. It also sets how long the `callbackToken` is valid,
* the `settings_schema`, and the organisation's `settings`,
* the `configuration` (`parameters` and `produces`),
* which workflow the agent belongs in, and at which position.

Next: [Agent endpoints](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent/agent-endpoints), for sending a completion later, reporting progress, and reading or attaching files.


# Agent endpoints

Three endpoints for agents that are running a step. They are for [agent developers](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent) only. API clients can't use them.

All three use the step's `callbackToken` from the envelope:

```
Authorization: Bearer <callbackToken>
```

A token belongs to one step (`agentRunId`), on one conversation, in one organisation. It is valid for the agent's configured timeout. The file endpoints work only while that step is still running.

Base URL: `https://main.formflow-dev.net`

### Send a completion or progress update

`POST /api/studio/webhooks/agent-communication`

Use this after you have [acknowledged](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent#answering-right-away-or-later) a step, to finish it or to tell the customer how it is going.

**Completion.** The body is the same JSON as an immediate answer:

```json
{
  "type": "completion",
  "agentRunId": "7b8c9d0e-…",
  "isComplete": true,
  "outputPayload": { "quoteReference": "Q-10442" },
  "outputMessage": "Your quote Q-10442 is ready."
}
```

**Progress.** A short status note for the customer. The step keeps running:

```json
{
  "type": "progress",
  "agentRunId": "7b8c9d0e-…",
  "isComplete": false,
  "message": "Rating 14 vehicles, this takes about a minute."
}
```

* `isComplete` is required on both types and must be `false` on progress. A progress update with `isComplete: true` fails the step.
* Progress notes are shown in the chat. They are not emailed, because an email conversation gets only the final reply.
* At most 5 progress notes per step, each up to 500 characters. Notes past the limit are ignored.

**Response.** Every valid request receives the same reply, whatever the state of the run:

```
202 { "status": "accepted" }
```

This is so the reply never reveals whether a run exists. A completion for a step that has already finished or timed out is ignored.

* `400`: the body is malformed, for example a missing `isComplete`, an unknown `type`, or an `agentRunId` that is not a UUID.
* `401`: the token is missing or invalid, or it belongs to a different `agentRunId` than the one in the body.
* Request bodies can be up to 1 MB.

### Download a file

`GET /api/studio/agent-files/{fileId}`

Swap a `fileId` from the envelope's `attachments` for the file itself. The response is a `302` redirect to a download link that is valid for 5 minutes, so follow the redirect, or read the `Location` header.

You can download:

* any file in the envelope's `attachments` (the conversation's documents), and
* the files of a submission created in the same conversation, for example after an earlier step passed you a `submissionId`.

A missing or invalid token returns `401`. Every other refusal returns `404`, including an unknown id, a file from another conversation, an upload that never finished, and a step that is no longer running.

```bash
curl -L -H "Authorization: Bearer $CALLBACK_TOKEN" \
  "https://main.formflow-dev.net/api/studio/agent-files/$FILE_ID" -o document.pdf
```

{% hint style="info" %}
Don't send the `Authorization` header to the storage URL you are redirected to. The link is already signed. Most HTTP clients, `curl -L` included, drop the header on a cross-host redirect.
{% endhint %}

### Attach a document you generated

`POST /api/studio/agent-files`

Add a document your agent created, such as a quote PDF or a bordereau, to the conversation. It appears with the conversation's files in the Nora web app. On email, it is attached to the run's final reply, if the run finishes with an answer. A run that fails, or that stops to ask for missing fields, sends no attachments.

```json
{
  "filename": "quote-Q-10442.pdf",
  "content": "JVBERi0xLjcKJeLjz9MK…",
  "caption": "Here is your quote."
}
```

<table><thead><tr><th width="120">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>filename</code></td><td>Required, up to 255 characters, stored as at most 200. The extension sets the file type, which must be one of <code>pdf</code>, <code>doc</code>, <code>docx</code>, <code>xls</code>, <code>xlsx</code>, <code>csv</code>, <code>jpg</code>, <code>jpeg</code>, <code>png</code>, <code>gif</code>, <code>heic</code>.</td></tr><tr><td><code>content</code></td><td>Required. The file's bytes, base64-encoded. Up to 10 MB before encoding.</td></tr><tr><td><code>caption</code></td><td>Optional, up to 500 characters. The text shown with the document in the conversation. Write it in the conversation's language.</td></tr></tbody></table>

**Response**

```json
{ "fileId": "c3e4f5a6-…", "filename": "quote-Q-10442.pdf", "size": 48211 }
```

The document is always stored on the step's own conversation. You can't choose another one.

Errors: `400` for a type that isn't allowed, empty content, or content over 10 MB. `401` for a missing or invalid token. `404` if the step is no longer running.

Limits for the final email: at most 5 generated documents and 15 MB in total. Documents over the limit stay in the conversation but are not attached to the email.


# Processing limitations

In order to ensure reliable processing, Formflow enforces some limits on the types and sizes of files that it will process.&#x20;

These limitations remain the same, regardless of whether the interaction is happening via the web interface, over email, via a chat agent, or another channel.

### General limitations <a href="#file-attachment-limits" id="file-attachment-limits"></a>

* The size of any one file may not exceed 24MB.&#x20;
* only the following file types are allowed:&#x20;
  * pdf
  * doc, docx
  * csv
  * xls, xlsx
  * gif, png, jpg or jpeg, heic
* (if submitting over email) the submission must be sent at a valid target address

{% hint style="info" %}

#### Formflow will only process a *complete* submission

If, for example, one file out five does not conform to these limitations, then the entire submission will *not* be processed. This is to ensure that no data is omitted by accident.
{% endhint %}

### Restrictions on Excel files

Excel files are processed automatically, but as a workaround to excessively large workbooks, each worksheet will be truncated to 60 columns × 400 rows. If a worksheet in the Excel file exceeds these dimensions, the excess cells will be automatically trimmed. Only `.xlsx`, `.xls` files are supported.

### Feedback to errors

If any of the above problems are faced during processing, then the user will be informed via the UI, or they will receive a "failed" response email in reply. Whenever possible, they will be given a detailed error message, repeating much of the notes on this page.


# API documentation

Nora exposes a RESTful API, which uses standard HTTP verbs, response codes and authentication methods. Additionally, we use webhooks to notify about submission events. You should expect JSON-encoded response payloads.

### Getting started <a href="#getting-started" id="getting-started"></a>

To get started building an integration layer on top of Nora, you will need the following:

* A Nora tenant account, preferably a sandboxed demo account
* API authentication credentials, issued by Customer Support
* At least one template is defined in your account
* Some test files to submit

### Data flow <a href="#data-flow" id="data-flow"></a>

The basic data flow is as follows:

1. **Submit:** the end user submits some files for processing via the web UI, over email or via API. They also specify a Template.
2. **Process:** Nora creates a Submission and processes the files therein. A Submission in `processing` status is made available over the API.
3. **Validate:** once a Submission is processed, the end user reviews the extraction results for accuracy and completeness. They may also add additional details manually. Once happy, they will mark the submission as `completed`.
4. **Consume:** third party integrations poll Nora for new Submissions, and if a new `completed` submission is found, process it according to internal business logic.

{% hint style="info" %}
[Agentic workflows](https://docs.ai.insly.com/nora/agentic-workflows) follow a different flow: you start a run, poll it, then read the submission it created. See [Run agentic extraction via API](https://docs.ai.insly.com/nora/agentic-workflows/run-agentic-extraction-via-api).
{% endhint %}


# Authentication and limits

To interact with the Nora API, you need to authenticate your requests using a token. All API requests are made to `https://main.formflow-dev.net`. All requests should be made using HTTPS.

### Obtain credentials <a href="#obtain-credentials" id="obtain-credentials"></a>

To access the Nora API, you will need a `clientId` and `clientSecret` value, which are provided by Nora Customer Support upon request. You will also need to know your `organizationId` value.

{% hint style="info" %}

#### Keep your credentials secure

Ensure your credentials (clientId, clientSecret, and organizationId) are kept secure. Do not expose them in client-side code or public repositories. Should a secret value or its hash surface in a public leaks database, Nora will pre-emptively deactivate such credentials.
{% endhint %}

You can exchange these for a `Bearer` token, valid for 3600 seconds (1 hour):

**Endpoint**

[`POST /api/token`](broken://pages/d52e928cc03ab5f837a429392ee63d6a50d18721#post-token)

**Headers**

`Accept: application/jsonContent-Type: application/json`

**Example request body**

```json
{
  "clientId": "2mvc4Ev4qpU8Y0FbADRq4xpZOhf",
  "clientSecret": "{zPYnGM$c&p+NLH0JNm-xdD'6+VHVuE`1R/xe(7+*eSAIOW^C~)M:8H_32Vd#{J",
  "organizationId": "2nHy8pbeoD5CM9WbjvyGj1VKoUu"
}
```

**Example 200 response**

```json
{
  "token": "eyJhbGciOiJSUzI1NiIs...Ce7EdUsAw",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

### Authenticate your requests <a href="#authenticate-your-requests" id="authenticate-your-requests"></a>

You can use the token in the response to authenticate all subsequent requests by including it in the Authorization header: `Authorization: Bearer <your_token>`

### Refreshing the token <a href="#refreshing-the-token" id="refreshing-the-token"></a>

Since the token is valid for 3600 seconds (1 hour), you will need to repeat the token request process to refresh your token. Ensure your application is designed to handle token expiration by checking against the `expires_in` value in the response.

### Rate Limiting <a href="#rate-limiting" id="rate-limiting"></a>

The API enforces a rate limit of 60 requests per minute to ensure fair usage and maintain performance. If you exceed this limit, the API will return a `429 Too Many Requests` response code. When this occurs, you must wait until the rate limit resets before making additional requests. To avoid interruptions, ensure your application adheres to the rate limit policy.


# Health check

Use this endpoint to check whether Nora is up before or between API calls. It needs no token, is not tied to your organisation, and changes nothing.

**Endpoint**

`GET /api/heartbeat`

Nora checks its database, cache and job queue on every call. Each check times out after 3 seconds.

**Example 200 response**

```json
{
  "status": "healthy",
  "envName": "production"
}
```

| Field     | Description                                                                                  |
| --------- | -------------------------------------------------------------------------------------------- |
| `status`  | `healthy` when every dependency responded, `unhealthy` when at least one did not.            |
| `envName` | The environment that answered. Use it to confirm you are calling the environment you expect. |

{% hint style="warning" %}

#### Read the status field, not only the HTTP code

The endpoint returns `200` when Nora is reachable, even if `status` is `unhealthy`. Treat Nora as healthy only when the response is `200` **and** `status` is `healthy`. A timeout, a connection error or a `5xx` means Nora is unreachable.
{% endhint %}

### Do not use other endpoints as a health check

Use this endpoint for health monitoring rather than a business endpoint such as `GET /api/webhook/subscriptions`. Business endpoints check your token's permissions and count towards your [rate limit](https://docs.ai.insly.com/nora/api-documentation/authentication-and-limits#rate-limiting), so a permission change can make Nora look down when it is not.

To confirm that your credentials still work, request a token with [`POST /api/token`](https://docs.ai.insly.com/nora/api-documentation/authentication-and-limits#obtain-credentials). That is a separate check from service health.


# API Client Management

Manage API clients and credentials

## GET /api-clients

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"API Client Management","description":"Manage API clients and credentials"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"ListApiClientsResponseDto":{"type":"object","properties":{"clients":{"type":"array","items":{"$ref":"#/components/schemas/ApiClient"}}},"required":["clients"]},"ApiClient":{"type":"object","properties":{}}}},"paths":{"/api-clients":{"get":{"operationId":"ApiClientsController_listApiClients","parameters":[],"responses":{"200":{"description":"API clients retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListApiClientsResponseDto"}}}}},"tags":["API Client Management"]}}}}
```

## POST /api-clients

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"API Client Management","description":"Manage API clients and credentials"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"CreateApiClientsRequestDto":{"type":"object","properties":{}},"CreateApiClientsResponseDto":{"type":"object","properties":{"clientSecret":{"type":"string","description":"The raw client secret (only shown once during creation)"},"message":{"type":"string","description":"Important message about storing the secret"}},"required":["clientSecret","message"]}}},"paths":{"/api-clients":{"post":{"operationId":"ApiClientsController_createApiClient","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiClientsRequestDto"}}}},"responses":{"201":{"description":"API client created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiClientsResponseDto"}}}}},"tags":["API Client Management"]}}}}
```

## DELETE /api-clients/{clientId}

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"API Client Management","description":"Manage API clients and credentials"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"RevokeApiClientResponseDto":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/api-clients/{clientId}":{"delete":{"operationId":"ApiClientsController_revokeApiClient","parameters":[{"name":"clientId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"API client revoked successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeApiClientResponseDto"}}}}},"tags":["API Client Management"]}}}}
```

## PATCH /api-clients/{clientId}/rotate-secret

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"API Client Management","description":"Manage API clients and credentials"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"RotateSecretResponseDto":{"type":"object","properties":{"clientId":{"type":"string"},"clientSecret":{"type":"string"},"message":{"type":"string"}},"required":["clientId","clientSecret","message"]}}},"paths":{"/api-clients/{clientId}/rotate-secret":{"patch":{"operationId":"ApiClientsController_rotateSecret","parameters":[{"name":"clientId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Secret rotated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateSecretResponseDto"}}}}},"tags":["API Client Management"]}}}}
```


# API Token

Token generation and management

## Get API access token

> Exchange API client credentials for an access token. Use this token in the Authorization header as "Bearer \<token>" for authenticated API requests.

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"API Token","description":"Token generation and management"}],"paths":{"/api/token":{"post":{"description":"Exchange API client credentials for an access token. Use this token in the Authorization header as \"Bearer <token>\" for authenticated API requests.","operationId":"TokenController_getToken","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiClientsRequestDto"}}}},"responses":{"200":{"description":"Successfully authenticated and returned access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenResponseDto"}}}},"400":{"description":"Bad request - missing or invalid parameters"},"401":{"description":"Invalid credentials or unauthorized"}},"summary":"Get API access token","tags":["API Token"]}}},"components":{"schemas":{"ApiClientsRequestDto":{"type":"object","properties":{"clientId":{"type":"string","description":"The API client ID provided when the API client was created"},"clientSecret":{"type":"string","description":"The API client secret provided when the API client was created"},"organizationId":{"type":"string","description":"The organization ID associated with this API client"}},"required":["clientId","clientSecret","organizationId"]},"GetTokenResponseDto":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token to use for authenticated API requests"},"token_type":{"type":"string","description":"Type of token (always \"Bearer\")"},"expires_in":{"type":"number","description":"Token expiration time in seconds"}},"required":["token","token_type","expires_in"]}}}}
```


# Submissions

Operations related to form submissions

## GET /api/submission

> Get submissions list

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/submission":{"get":{"operationId":"SubmissionController_getAllSubmissions","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"perPage","required":false,"in":"query","description":"Items per page (default: 10)","schema":{"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field (default: createdAt)","schema":{"enum":["createdAt","updatedAt"],"type":"string"}},{"name":"sortDir","required":false,"in":"query","description":"Sort direction (default: desc)","schema":{"enum":["asc","desc"],"type":"string"}},{"name":"status","required":false,"in":"query","description":"Comma-separated list of statuses to filter by","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns a paginated list of submissions"}},"summary":"Get submissions list","tags":["Submissions"]}}}}
```

## POST /api/submission

> Create a new submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"CreateSubmissionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the submission"},"name":{"type":"string","description":"Submission name"},"templateId":{"type":"number","description":"ID of the associated template"},"uploaderUserId":{"type":"string","description":"ID of the user who uploaded the submission"},"userId":{"type":"string","description":"ID of the user associated with the submission"},"emailSender":{"type":"string","description":"Email address of the sender"},"emailBody":{"type":"string","description":"Email body or additional context"},"emailMessageId":{"type":"string","description":"Email message ID"},"payload":{"type":"object","description":"Submission payload data"},"manualPayload":{"type":"object","description":"Manual payload data"},"metaPayload":{"type":"object","description":"Metadata payload"}}},"SubmissionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the submission"},"submissionNumber":{"type":"number","description":"Submission sequence number"},"name":{"type":"string","description":"Submission name"},"template":{"description":"Associated template","allOf":[{"$ref":"#/components/schemas/Template"}]},"templateId":{"type":"number","description":"ID of the associated template"},"uploaderUserId":{"type":"string","description":"ID of the user who uploaded the submission"},"userId":{"type":"string","description":"ID of the user associated with the submission"},"files":{"description":"Files attached to the submission","type":"array","items":{"type":"string"}},"status":{"description":"Current status of the submission","allOf":[{"$ref":"#/components/schemas/SubmissionStatus"}]},"emailSender":{"type":"string","description":"Email address of the sender"},"emailBody":{"type":"string","description":"Email body or additional context"},"emailMessageId":{"type":"string","description":"Email message ID"},"payload":{"type":"object","description":"Submission payload data"},"manualPayload":{"type":"object","description":"Manual payload data"},"metaPayload":{"type":"object","description":"Metadata payload"},"OBEExtraction":{"type":"string","description":"ID of the old backend extraction event"},"NBEExtraction":{"type":"string","description":"ID of the new backend extraction event"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was last updated"}},"required":["id","submissionNumber","name","template","templateId","files","status","createdAt","updatedAt"]},"Template":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the template"},"templateId":{"type":"string","description":"The UUID of the template"},"name":{"type":"string","description":"The name of the template"},"description":{"type":"string","description":"The description of the template"},"version":{"type":"number","description":"The version of the template"},"schema":{"type":"object","description":"The schema of the template"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendorSchema":{"type":"object","description":"The vendor schema"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"},"aiGenerated":{"type":"boolean","description":"Whether the template was generated using AI"},"emailAlias":{"type":"string","description":"The email alias"},"extractionStrategyId":{"type":"string","description":"The uuid of extraction strategy template uses."},"extractionStrategy":{"description":"Associated extraction strategy","allOf":[{"$ref":"#/components/schemas/Strategy"}]},"referenceStrategy":{"description":"Associated reference strategy","allOf":[{"$ref":"#/components/schemas/Strategy"}]},"state":{"type":"string","description":"The state of the template","enum":["draft","published"],"default":"published"},"parsingInstructions":{"type":"object","description":"the parsing instructions for a template"}},"required":["id","templateId","name","version","aiGenerated","extractionStrategyId","extractionStrategy","referenceStrategy","state","parsingInstructions"]},"Strategy":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the strategy"},"identifier":{"type":"string","description":"Identifier of the strategy type","enum":["extraction-claude-3-7","extraction-gemini-2-5-loose","extraction-claude-3-7-thinking","extraction-atomic"]},"type":{"type":"string","description":"Type of the strategy","default":"extraction"},"displayName":{"type":"string","description":"Display name of the strategy"},"description":{"type":"string","description":"Description of the strategy"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was last updated"}},"required":["id","identifier","type","displayName","createdAt","updatedAt"]},"SubmissionStatus":{"type":"string","enum":["created","processing","processing-failed","processed","in-review","completed","exported","export-failed","discarded","preparing","queued"]}}},"paths":{"/api/submission":{"post":{"operationId":"SubmissionController_createSubmission","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubmissionDto"}}}},"responses":{"201":{"description":"The submission has been successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionDto"}}}}},"summary":"Create a new submission","tags":["Submissions"]}}}}
```

## GET /api/submission/{id}

> Get submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/submission/{id}":{"get":{"operationId":"SubmissionController_getSubmissionById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Get submission","tags":["Submissions"]}}}}
```

## PATCH /api/submission/{id}

> Update submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"UpdateSubmissionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the submission"},"submissionNumber":{"type":"number","description":"Submission sequence number"},"name":{"type":"string","description":"Submission name"},"templateId":{"type":"number","description":"ID of the associated template"},"uploaderUserId":{"type":"string","description":"ID of the user who uploaded the submission"},"userId":{"type":"string","description":"ID of the user associated with the submission"},"status":{"description":"Current status of the submission","allOf":[{"$ref":"#/components/schemas/SubmissionStatus"}]},"emailSender":{"type":"string","description":"Email address of the sender"},"emailBody":{"type":"string","description":"Email body or additional context"},"emailMessageId":{"type":"string","description":"Email message ID"},"payload":{"type":"object","description":"Submission payload data"},"manualPayload":{"type":"object","description":"Manual payload data"},"metaPayload":{"type":"object","description":"Metadata payload"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was last updated"}}},"SubmissionStatus":{"type":"string","enum":["created","processing","processing-failed","processed","in-review","completed","exported","export-failed","discarded","preparing","queued"]}}},"paths":{"/api/submission/{id}":{"patch":{"operationId":"SubmissionController_updateSubmission","parameters":[{"name":"id","required":true,"in":"path","description":"Submission ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubmissionDto"}}}},"responses":{"200":{"description":"The submission has been successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubmissionDto"}}}}},"summary":"Update submission","tags":["Submissions"]}}}}
```

## GET /api/submission/{id}/references

> Get references for submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/submission/{id}/references":{"get":{"operationId":"SubmissionController_getSubmissionReferences","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns references for a specific submission"}},"summary":"Get references for submission","tags":["Submissions"]}}}}
```

## GET /api/submission/{id}/events

> Get all events for a submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"Event":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the event"},"submissionId":{"type":"string","description":"Related submission ID","nullable":true},"type":{"type":"string","description":"Type of event","enum":["upload","email","conversion","extraction","export","discard","reference","generate-schema","metadata"]},"state":{"type":"string","description":"Current state of the event","enum":["pending","succeed","fail"]},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the event was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the event was last updated"}},"required":["id","submissionId","type","state","createdAt","updatedAt"]}}},"paths":{"/api/submission/{id}/events":{"get":{"operationId":"SubmissionController_getSubmissionEvents","parameters":[{"name":"id","required":true,"in":"path","description":"Submission ID to retrieve events for","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns all events and their current status for the specified submission","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}},"404":{"description":"Submission with ID 123e4567-e89b-12d3-a456-426614174001 not found"}},"summary":"Get all events for a submission","tags":["Submissions"]}}}}
```

## POST /api/submission/{id}/upload

> Get temporary S3 URL for client-side upload

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"UploadRequestDto":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file to upload"},"contentType":{"type":"string","description":"MIME type of the file"}},"required":["fileName","contentType"]}}},"paths":{"/api/submission/{id}/upload":{"post":{"operationId":"SubmissionController_getUploadUrl","parameters":[{"name":"id","required":true,"in":"path","description":"Submission ID","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Upload file details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequestDto"}}}},"responses":{"201":{"description":""}},"summary":"Get temporary S3 URL for client-side upload","tags":["Submissions"]}}}}
```

## POST /api/submission/{id}/export

> Export submission to ledger

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/submission/{id}/export":{"post":{"operationId":"SubmissionController_exportSubmission","parameters":[{"name":"id","required":true,"in":"path","description":"Submission ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Submission successfully exported"},"404":{"description":"Submission not found"},"500":{"description":"Export failed"}},"summary":"Export submission to ledger","tags":["Submissions"]}}}}
```


# Templates

Operations related to form templates

## GET /api/template

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/template":{"get":{"operationId":"TemplateController_getAllTemplates","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"perPage","required":false,"in":"query","description":"Items per page (default: 100)","schema":{"type":"number"}}],"responses":{"200":{"description":"Returns a paginated list of templates"}},"tags":["Templates"]}}}}
```

## POST /api/template

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"CreateTemplateDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the template"},"description":{"type":"string","description":"The description of the template"},"version":{"type":"number","description":"The version of the template"},"schema":{"type":"object","description":"The schema of the template"},"aiGenerated":{"type":"boolean","description":"Wheter the template was generated using AI"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendorSchema":{"type":"object","description":"The vendor schema"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"},"emailAlias":{"type":"string","description":"The email alias"},"state":{"type":"string","description":"The state of the template","enum":["draft","published"],"default":"published"}},"required":["name","version"]}}},"paths":{"/api/template":{"post":{"operationId":"TemplateController_createTemplate","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplateDto"}}}},"responses":{"201":{"description":"Creates a new template"}},"tags":["Templates"]}}}}
```

## GET /api/template/{id}

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/template/{id}":{"get":{"operationId":"TemplateController_getTemplateById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"tags":["Templates"]}}}}
```

## PUT /api/template/{id}

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"UpdateTemplateDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the template"},"description":{"type":"string","description":"The description of the template"},"version":{"type":"number","description":"The version of the template"},"schema":{"type":"object","description":"The schema of the template"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendorSchema":{"type":"object","description":"The vendor schema"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"},"emailAlias":{"type":"string","description":"The email alias"},"extractionStrategyId":{"type":"string","description":"The uuid of extraction strategy template uses."},"state":{"type":"string","description":"The state of the template","enum":["draft","published"],"default":"published"},"parsingInstructions":{"type":"object","description":"the parsing instructions for a template"}}}}},"paths":{"/api/template/{id}":{"put":{"operationId":"TemplateController_updateTemplate","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplateDto"}}}},"responses":{"200":{"description":"Updates an existing template"},"413":{"description":"Payload too large"}},"tags":["Templates"]}}}}
```

## DELETE /api/template/{id}

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/template/{id}":{"delete":{"operationId":"TemplateController_deleteTemplate","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"204":{"description":"Soft deletes an existing template"}},"tags":["Templates"]}}}}
```

## PATCH /api/template/{id}

> Update template

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"UpdateTemplateDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the template"},"description":{"type":"string","description":"The description of the template"},"version":{"type":"number","description":"The version of the template"},"schema":{"type":"object","description":"The schema of the template"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendorSchema":{"type":"object","description":"The vendor schema"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"},"emailAlias":{"type":"string","description":"The email alias"},"extractionStrategyId":{"type":"string","description":"The uuid of extraction strategy template uses."},"state":{"type":"string","description":"The state of the template","enum":["draft","published"],"default":"published"},"parsingInstructions":{"type":"object","description":"the parsing instructions for a template"}}}}},"paths":{"/api/template/{id}":{"patch":{"operationId":"TemplateController_patchTemplate","parameters":[{"name":"id","required":true,"in":"path","description":"Template ID","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplateDto"}}}},"responses":{"200":{"description":"The template has been successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplateDto"}}}}},"summary":"Update template","tags":["Templates"]}}}}
```

## GET /api/template/{id}/submissions

>

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/template/{id}/submissions":{"get":{"operationId":"TemplateController_getTemplateSubmissions","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"perPage","required":false,"in":"query","description":"Items per page (default: 10)","schema":{"type":"number"}}],"responses":{"200":{"description":"Returns a paginated list of submissions for the specified template"}},"tags":["Templates"]}}}}
```

## POST /api/template/import-from-ledger

> Import schema from Ledger

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"ImportFromLedgerDto":{"type":"object","properties":{"schema":{"type":"object","description":"The updated schema from Ledger"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendor_schema_name":{"type":"string","description":"The vendor schema name (alternative)"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendor_schema_version":{"type":"number","description":"The vendor schema version (alternative)"},"vendorSchema":{"type":"object","description":"The vendor schema"},"vendor_schema":{"type":"object","description":"The vendor schema (alternative snake_case)"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"}}}}},"paths":{"/api/template/import-from-ledger":{"post":{"operationId":"TemplateController_importSchemaFromLedger","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportFromLedgerDto"}}}},"responses":{"201":{"description":"transforms Ledger schema into a formflow template"}},"summary":"Import schema from Ledger","tags":["Templates"]}}}}
```

## POST /api/template/{id}/duplicate

> Duplicate an existing template

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/template/{id}/duplicate":{"post":{"operationId":"TemplateController_duplicateTemplate","parameters":[{"name":"id","required":true,"in":"path","description":"Template ID to duplicate","schema":{"type":"number"}}],"responses":{"201":{"description":"Creates a duplicate of the existing template with all AI hints preserved"}},"summary":"Duplicate an existing template","tags":["Templates"]}}}}
```

## POST /api/template/{id}/update-from-ledger

> Import updated schema from Ledger

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Templates","description":"Operations related to form templates"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"ImportFromLedgerDto":{"type":"object","properties":{"schema":{"type":"object","description":"The updated schema from Ledger"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendor_schema_name":{"type":"string","description":"The vendor schema name (alternative)"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendor_schema_version":{"type":"number","description":"The vendor schema version (alternative)"},"vendorSchema":{"type":"object","description":"The vendor schema"},"vendor_schema":{"type":"object","description":"The vendor schema (alternative snake_case)"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"}}}}},"paths":{"/api/template/{id}/update-from-ledger":{"post":{"operationId":"TemplateController_importFromLedger","parameters":[{"name":"id","required":true,"in":"path","description":"Template ID to update from Ledger","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportFromLedgerDto"}}}},"responses":{"201":{"description":"Creates a new template with updated schema from Ledger while preserving AI hints"}},"summary":"Import updated schema from Ledger","tags":["Templates"]}}}}
```


# Processing

Operations for processing submissions

## Start processing

> Use this endpoint to start processing a new submission. Provide the submission data in the request body.

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Processing","description":"Operations for processing submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"SubmissionEntryDTO":{"type":"object","properties":{"submissionId":{"type":"string","description":"The ID of the submission"},"generateTemplate":{"type":"boolean","description":"Whether to generate a template for the submission","default":false}},"required":["submissionId"]},"SubmissionResponseDto":{"type":"object","properties":{"submissionId":{"type":"string","description":"The ID of the submission"},"message":{"type":"string","description":"Response message"},"templateId":{"type":"number","description":"The ID of the template if generated"}},"required":["submissionId","message"]}}},"paths":{"/api/processing":{"post":{"description":"Use this endpoint to start processing a new submission. Provide the submission data in the request body.","operationId":"ProcessingController_startProcessing","parameters":[],"requestBody":{"required":true,"description":"The submission data to be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionEntryDTO"}}}},"responses":{"200":{"description":"Returns a message indicating that the processing service has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionResponseDto"}}}}},"summary":"Start processing","tags":["Processing"]}}}}
```


# Files

File management operations

## GET /api/file/{id}

> Get file by ID

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Files","description":"File management operations"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"FileDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the file"},"name":{"type":"string","description":"Name of the file"},"fileName":{"type":"string","description":"Original file name"},"fileType":{"type":"string","description":"Type of the file (e.g., MIME type)"},"fileSize":{"type":"number","description":"Size of the file in bytes"},"url":{"type":"string","description":"Public URL of the file"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the file was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the file was last updated"}},"required":["id","fileName","fileType","fileSize","url","createdAt","updatedAt"]}}},"paths":{"/api/file/{id}":{"get":{"operationId":"FileController_getFileById","parameters":[{"name":"id","required":true,"in":"path","description":"File ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the file details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDto"}}}},"404":{"description":"File not found"}},"summary":"Get file by ID","tags":["Files"]}}}}
```

## DELETE /api/file/{id}

> Delete a file

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Files","description":"File management operations"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/file/{id}":{"delete":{"operationId":"FileController_deleteFile","parameters":[{"name":"id","required":true,"in":"path","description":"File ID","schema":{"type":"string"}}],"responses":{"204":{"description":"The file has been successfully deleted"},"404":{"description":"File not found"}},"summary":"Delete a file","tags":["Files"]}}}}
```

## GET /api/file/{id}/view

> View/download file directly

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Files","description":"File management operations"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/file/{id}/view":{"get":{"operationId":"FileController_viewFile","parameters":[{"name":"id","required":true,"in":"path","description":"File ID","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirects to file download"},"404":{"description":"File not found"}},"summary":"View/download file directly","tags":["Files"]}}}}
```


# Webhooks

Webhook management and events

## GET /api/webhook/events

> Get all available webhook event types

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhook management and events"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"WebhookEventInfoDto":{"type":"object","properties":{"eventType":{"type":"string","description":"Event type identifier"},"description":{"type":"string","description":"Human-readable description of when this event is triggered"},"examplePayload":{"type":"object","description":"Example payload structure for this event type"}},"required":["eventType","description","examplePayload"]}}},"paths":{"/api/webhook/events":{"get":{"operationId":"WebhookController_getAvailableEvents","parameters":[],"responses":{"200":{"description":"Returns list of all webhook event types with descriptions and example payloads","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventInfoDto"}}}}}},"summary":"Get all available webhook event types","tags":["Webhooks"]}}}}
```

## POST /api/webhook/subscription

> Create webhook subscription

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhook management and events"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"WebhookSubscriberCreateDto":{"type":"object","properties":{"event":{"description":"Event type that triggers the webhook","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"url":{"type":"string","description":"URL where webhook notifications will be sent"}},"required":["event","url"]},"WebhookEventType":{"type":"string","enum":["extracted","export","validation-success"]},"WebhookSubscriber":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the webhook subscriber"},"event":{"description":"Event type that triggers the webhook","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"url":{"type":"string","description":"URL where webhook notifications will be sent"},"secret":{"type":"object","description":"Secret token used for HMAC signature generation"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was last updated"}},"required":["id","event","url","secret","createdAt","updatedAt"]}}},"paths":{"/api/webhook/subscription":{"post":{"operationId":"WebhookController_createSubscription","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriberCreateDto"}}}},"responses":{"201":{"description":"The webhook subscription has been created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriber"}}}},"400":{"description":"Bad request - URL and event are required"},"500":{"description":"Internal server error"}},"summary":"Create webhook subscription","tags":["Webhooks"]}}}}
```

## GET /api/webhook/subscriptions

> Get all webhook subscriptions

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhook management and events"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"WebhookSubscriber":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the webhook subscriber"},"event":{"description":"Event type that triggers the webhook","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"url":{"type":"string","description":"URL where webhook notifications will be sent"},"secret":{"type":"object","description":"Secret token used for HMAC signature generation"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was last updated"}},"required":["id","event","url","secret","createdAt","updatedAt"]},"WebhookEventType":{"type":"string","enum":["extracted","export","validation-success"]}}},"paths":{"/api/webhook/subscriptions":{"get":{"operationId":"WebhookController_getAllSubscriptions","parameters":[],"responses":{"200":{"description":"List of webhook subscriptions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscriber"}}}}},"500":{"description":"Internal server error"}},"summary":"Get all webhook subscriptions","tags":["Webhooks"]}}}}
```

## GET /api/webhook/subscription/{id}

> Get webhook subscription by ID

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhook management and events"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"WebhookSubscriber":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the webhook subscriber"},"event":{"description":"Event type that triggers the webhook","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"url":{"type":"string","description":"URL where webhook notifications will be sent"},"secret":{"type":"object","description":"Secret token used for HMAC signature generation"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was last updated"}},"required":["id","event","url","secret","createdAt","updatedAt"]},"WebhookEventType":{"type":"string","enum":["extracted","export","validation-success"]}}},"paths":{"/api/webhook/subscription/{id}":{"get":{"operationId":"WebhookController_getSubscriptionById","parameters":[{"name":"id","required":true,"in":"path","description":"Subscription ID","schema":{"type":"string"}}],"responses":{"200":{"description":"The webhook subscription details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriber"}}}},"404":{"description":"Subscription not found"},"500":{"description":"Internal server error"}},"summary":"Get webhook subscription by ID","tags":["Webhooks"]}}}}
```

## PUT /api/webhook/subscription/{id}

> Update webhook subscription

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhook management and events"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"WebhookSubscriberUpdateDto":{"type":"object","properties":{"event":{"description":"Event type that triggers the webhook","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"url":{"type":"string","description":"URL where webhook notifications will be sent"}}},"WebhookEventType":{"type":"string","enum":["extracted","export","validation-success"]},"WebhookSubscriber":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the webhook subscriber"},"event":{"description":"Event type that triggers the webhook","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"url":{"type":"string","description":"URL where webhook notifications will be sent"},"secret":{"type":"object","description":"Secret token used for HMAC signature generation"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was last updated"}},"required":["id","event","url","secret","createdAt","updatedAt"]}}},"paths":{"/api/webhook/subscription/{id}":{"put":{"operationId":"WebhookController_updateSubscription","parameters":[{"name":"id","required":true,"in":"path","description":"Subscription ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriberUpdateDto"}}}},"responses":{"200":{"description":"The updated webhook subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriber"}}}},"404":{"description":"Subscription not found"},"500":{"description":"Internal server error"}},"summary":"Update webhook subscription","tags":["Webhooks"]}}}}
```

## DELETE /api/webhook/subscription/{id}

> Delete webhook subscription

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhook management and events"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"WebhookSubscriberDeleteResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the delete operation was successful"}},"required":["success"]}}},"paths":{"/api/webhook/subscription/{id}":{"delete":{"operationId":"WebhookController_deleteSubscription","parameters":[{"name":"id","required":true,"in":"path","description":"Subscription ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription successfully deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriberDeleteResponseDto"}}}},"404":{"description":"Subscription not found"},"500":{"description":"Internal server error"}},"summary":"Delete webhook subscription","tags":["Webhooks"]}}}}
```


# Users

User management operations

## Get all users in the organization

> Returns all users that are members of the current organization.

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Users","description":"User management operations"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"UserDto":{"type":"object","properties":{"id":{"type":"string","description":"Clerk user ID"},"firstName":{"type":"string","description":"User first name","nullable":true},"lastName":{"type":"string","description":"User last name","nullable":true},"imageUrl":{"type":"string","description":"User profile image URL","nullable":true}},"required":["id"]}}},"paths":{"/api/users":{"get":{"description":"Returns all users that are members of the current organization.","operationId":"UserController_getUsers","parameters":[],"responses":{"200":{"description":"Returns an array of users with their information","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserDto"}}}}}},"summary":"Get all users in the organization","tags":["Users"]}}}}
```


# Models

## The CreateTemplateDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"CreateTemplateDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the template"},"description":{"type":"string","description":"The description of the template"},"version":{"type":"number","description":"The version of the template"},"schema":{"type":"object","description":"The schema of the template"},"aiGenerated":{"type":"boolean","description":"Wheter the template was generated using AI"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendorSchema":{"type":"object","description":"The vendor schema"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"},"emailAlias":{"type":"string","description":"The email alias"},"state":{"type":"string","description":"The state of the template","enum":["draft","published"],"default":"published"}},"required":["name","version"]}}}}
```

## The ImportFromLedgerDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"ImportFromLedgerDto":{"type":"object","properties":{"schema":{"type":"object","description":"The updated schema from Ledger"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendor_schema_name":{"type":"string","description":"The vendor schema name (alternative)"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendor_schema_version":{"type":"number","description":"The vendor schema version (alternative)"},"vendorSchema":{"type":"object","description":"The vendor schema"},"vendor_schema":{"type":"object","description":"The vendor schema (alternative snake_case)"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"}}}}}}
```

## The UpdateTemplateDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"UpdateTemplateDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the template"},"description":{"type":"string","description":"The description of the template"},"version":{"type":"number","description":"The version of the template"},"schema":{"type":"object","description":"The schema of the template"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendorSchema":{"type":"object","description":"The vendor schema"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"},"emailAlias":{"type":"string","description":"The email alias"},"extractionStrategyId":{"type":"string","description":"The uuid of extraction strategy template uses."},"state":{"type":"string","description":"The state of the template","enum":["draft","published"],"default":"published"},"parsingInstructions":{"type":"object","description":"the parsing instructions for a template"}}}}}}
```

## The FileDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"FileDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the file"},"name":{"type":"string","description":"Name of the file"},"fileName":{"type":"string","description":"Original file name"},"fileType":{"type":"string","description":"Type of the file (e.g., MIME type)"},"fileSize":{"type":"number","description":"Size of the file in bytes"},"url":{"type":"string","description":"Public URL of the file"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the file was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the file was last updated"}},"required":["id","fileName","fileType","fileSize","url","createdAt","updatedAt"]}}}}
```

## The Event object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"Event":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the event"},"submissionId":{"type":"string","description":"Related submission ID","nullable":true},"type":{"type":"string","description":"Type of event","enum":["upload","email","conversion","extraction","export","discard","reference","generate-schema","metadata"]},"state":{"type":"string","description":"Current state of the event","enum":["pending","succeed","fail"]},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the event was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the event was last updated"}},"required":["id","submissionId","type","state","createdAt","updatedAt"]}}}}
```

## The CreateSubmissionDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"CreateSubmissionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the submission"},"name":{"type":"string","description":"Submission name"},"templateId":{"type":"number","description":"ID of the associated template"},"uploaderUserId":{"type":"string","description":"ID of the user who uploaded the submission"},"userId":{"type":"string","description":"ID of the user associated with the submission"},"emailSender":{"type":"string","description":"Email address of the sender"},"emailBody":{"type":"string","description":"Email body or additional context"},"emailMessageId":{"type":"string","description":"Email message ID"},"payload":{"type":"object","description":"Submission payload data"},"manualPayload":{"type":"object","description":"Manual payload data"},"metaPayload":{"type":"object","description":"Metadata payload"}}}}}}
```

## The Strategy object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"Strategy":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the strategy"},"identifier":{"type":"string","description":"Identifier of the strategy type","enum":["extraction-claude-3-7","extraction-gemini-2-5-loose","extraction-claude-3-7-thinking","extraction-atomic"]},"type":{"type":"string","description":"Type of the strategy","default":"extraction"},"displayName":{"type":"string","description":"Display name of the strategy"},"description":{"type":"string","description":"Description of the strategy"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was last updated"}},"required":["id","identifier","type","displayName","createdAt","updatedAt"]}}}}
```

## The Template object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"Template":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the template"},"templateId":{"type":"string","description":"The UUID of the template"},"name":{"type":"string","description":"The name of the template"},"description":{"type":"string","description":"The description of the template"},"version":{"type":"number","description":"The version of the template"},"schema":{"type":"object","description":"The schema of the template"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendorSchema":{"type":"object","description":"The vendor schema"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"},"aiGenerated":{"type":"boolean","description":"Whether the template was generated using AI"},"emailAlias":{"type":"string","description":"The email alias"},"extractionStrategyId":{"type":"string","description":"The uuid of extraction strategy template uses."},"extractionStrategy":{"description":"Associated extraction strategy","allOf":[{"$ref":"#/components/schemas/Strategy"}]},"referenceStrategy":{"description":"Associated reference strategy","allOf":[{"$ref":"#/components/schemas/Strategy"}]},"state":{"type":"string","description":"The state of the template","enum":["draft","published"],"default":"published"},"parsingInstructions":{"type":"object","description":"the parsing instructions for a template"}},"required":["id","templateId","name","version","aiGenerated","extractionStrategyId","extractionStrategy","referenceStrategy","state","parsingInstructions"]},"Strategy":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the strategy"},"identifier":{"type":"string","description":"Identifier of the strategy type","enum":["extraction-claude-3-7","extraction-gemini-2-5-loose","extraction-claude-3-7-thinking","extraction-atomic"]},"type":{"type":"string","description":"Type of the strategy","default":"extraction"},"displayName":{"type":"string","description":"Display name of the strategy"},"description":{"type":"string","description":"Description of the strategy"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was last updated"}},"required":["id","identifier","type","displayName","createdAt","updatedAt"]}}}}
```

## The SubmissionStatus object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"SubmissionStatus":{"type":"string","enum":["created","processing","processing-failed","processed","in-review","completed","exported","export-failed","discarded","preparing","queued"]}}}}
```

## The SubmissionDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"SubmissionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the submission"},"submissionNumber":{"type":"number","description":"Submission sequence number"},"name":{"type":"string","description":"Submission name"},"template":{"description":"Associated template","allOf":[{"$ref":"#/components/schemas/Template"}]},"templateId":{"type":"number","description":"ID of the associated template"},"uploaderUserId":{"type":"string","description":"ID of the user who uploaded the submission"},"userId":{"type":"string","description":"ID of the user associated with the submission"},"files":{"description":"Files attached to the submission","type":"array","items":{"type":"string"}},"status":{"description":"Current status of the submission","allOf":[{"$ref":"#/components/schemas/SubmissionStatus"}]},"emailSender":{"type":"string","description":"Email address of the sender"},"emailBody":{"type":"string","description":"Email body or additional context"},"emailMessageId":{"type":"string","description":"Email message ID"},"payload":{"type":"object","description":"Submission payload data"},"manualPayload":{"type":"object","description":"Manual payload data"},"metaPayload":{"type":"object","description":"Metadata payload"},"OBEExtraction":{"type":"string","description":"ID of the old backend extraction event"},"NBEExtraction":{"type":"string","description":"ID of the new backend extraction event"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was last updated"}},"required":["id","submissionNumber","name","template","templateId","files","status","createdAt","updatedAt"]},"Template":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the template"},"templateId":{"type":"string","description":"The UUID of the template"},"name":{"type":"string","description":"The name of the template"},"description":{"type":"string","description":"The description of the template"},"version":{"type":"number","description":"The version of the template"},"schema":{"type":"object","description":"The schema of the template"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendorSchema":{"type":"object","description":"The vendor schema"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"},"aiGenerated":{"type":"boolean","description":"Whether the template was generated using AI"},"emailAlias":{"type":"string","description":"The email alias"},"extractionStrategyId":{"type":"string","description":"The uuid of extraction strategy template uses."},"extractionStrategy":{"description":"Associated extraction strategy","allOf":[{"$ref":"#/components/schemas/Strategy"}]},"referenceStrategy":{"description":"Associated reference strategy","allOf":[{"$ref":"#/components/schemas/Strategy"}]},"state":{"type":"string","description":"The state of the template","enum":["draft","published"],"default":"published"},"parsingInstructions":{"type":"object","description":"the parsing instructions for a template"}},"required":["id","templateId","name","version","aiGenerated","extractionStrategyId","extractionStrategy","referenceStrategy","state","parsingInstructions"]},"Strategy":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the strategy"},"identifier":{"type":"string","description":"Identifier of the strategy type","enum":["extraction-claude-3-7","extraction-gemini-2-5-loose","extraction-claude-3-7-thinking","extraction-atomic"]},"type":{"type":"string","description":"Type of the strategy","default":"extraction"},"displayName":{"type":"string","description":"Display name of the strategy"},"description":{"type":"string","description":"Description of the strategy"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was last updated"}},"required":["id","identifier","type","displayName","createdAt","updatedAt"]},"SubmissionStatus":{"type":"string","enum":["created","processing","processing-failed","processed","in-review","completed","exported","export-failed","discarded","preparing","queued"]}}}}
```

## The UploadRequestDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"UploadRequestDto":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file to upload"},"contentType":{"type":"string","description":"MIME type of the file"}},"required":["fileName","contentType"]}}}}
```

## The UpdateSubmissionDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"UpdateSubmissionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the submission"},"submissionNumber":{"type":"number","description":"Submission sequence number"},"name":{"type":"string","description":"Submission name"},"templateId":{"type":"number","description":"ID of the associated template"},"uploaderUserId":{"type":"string","description":"ID of the user who uploaded the submission"},"userId":{"type":"string","description":"ID of the user associated with the submission"},"status":{"description":"Current status of the submission","allOf":[{"$ref":"#/components/schemas/SubmissionStatus"}]},"emailSender":{"type":"string","description":"Email address of the sender"},"emailBody":{"type":"string","description":"Email body or additional context"},"emailMessageId":{"type":"string","description":"Email message ID"},"payload":{"type":"object","description":"Submission payload data"},"manualPayload":{"type":"object","description":"Manual payload data"},"metaPayload":{"type":"object","description":"Metadata payload"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was last updated"}}},"SubmissionStatus":{"type":"string","enum":["created","processing","processing-failed","processed","in-review","completed","exported","export-failed","discarded","preparing","queued"]}}}}
```

## The WebhookEventInfoDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"WebhookEventInfoDto":{"type":"object","properties":{"eventType":{"type":"string","description":"Event type identifier"},"description":{"type":"string","description":"Human-readable description of when this event is triggered"},"examplePayload":{"type":"object","description":"Example payload structure for this event type"}},"required":["eventType","description","examplePayload"]}}}}
```

## The WebhookEventType object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"WebhookEventType":{"type":"string","enum":["extracted","export","validation-success"]}}}}
```

## The WebhookSubscriberCreateDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"WebhookSubscriberCreateDto":{"type":"object","properties":{"event":{"description":"Event type that triggers the webhook","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"url":{"type":"string","description":"URL where webhook notifications will be sent"}},"required":["event","url"]},"WebhookEventType":{"type":"string","enum":["extracted","export","validation-success"]}}}}
```

## The WebhookSubscriber object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"WebhookSubscriber":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the webhook subscriber"},"event":{"description":"Event type that triggers the webhook","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"url":{"type":"string","description":"URL where webhook notifications will be sent"},"secret":{"type":"object","description":"Secret token used for HMAC signature generation"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the webhook subscription was last updated"}},"required":["id","event","url","secret","createdAt","updatedAt"]},"WebhookEventType":{"type":"string","enum":["extracted","export","validation-success"]}}}}
```

## The WebhookSubscriberUpdateDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"WebhookSubscriberUpdateDto":{"type":"object","properties":{"event":{"description":"Event type that triggers the webhook","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"url":{"type":"string","description":"URL where webhook notifications will be sent"}}},"WebhookEventType":{"type":"string","enum":["extracted","export","validation-success"]}}}}
```

## The WebhookSubscriberDeleteResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"WebhookSubscriberDeleteResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the delete operation was successful"}},"required":["success"]}}}}
```

## The UserDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"UserDto":{"type":"object","properties":{"id":{"type":"string","description":"Clerk user ID"},"firstName":{"type":"string","description":"User first name","nullable":true},"lastName":{"type":"string","description":"User last name","nullable":true},"imageUrl":{"type":"string","description":"User profile image URL","nullable":true}},"required":["id"]}}}}
```

## The SubmissionEntryDTO object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"SubmissionEntryDTO":{"type":"object","properties":{"submissionId":{"type":"string","description":"The ID of the submission"},"generateTemplate":{"type":"boolean","description":"Whether to generate a template for the submission","default":false}},"required":["submissionId"]}}}}
```

## The SubmissionResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"SubmissionResponseDto":{"type":"object","properties":{"submissionId":{"type":"string","description":"The ID of the submission"},"message":{"type":"string","description":"Response message"},"templateId":{"type":"number","description":"The ID of the template if generated"}},"required":["submissionId","message"]}}}}
```

## The CreateApiClientsRequestDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"CreateApiClientsRequestDto":{"type":"object","properties":{}}}}}
```

## The CreateApiClientsResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"CreateApiClientsResponseDto":{"type":"object","properties":{"clientSecret":{"type":"string","description":"The raw client secret (only shown once during creation)"},"message":{"type":"string","description":"Important message about storing the secret"}},"required":["clientSecret","message"]}}}}
```

## The ApiClient object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"ApiClient":{"type":"object","properties":{}}}}}
```

## The ListApiClientsResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"ListApiClientsResponseDto":{"type":"object","properties":{"clients":{"type":"array","items":{"$ref":"#/components/schemas/ApiClient"}}},"required":["clients"]},"ApiClient":{"type":"object","properties":{}}}}}
```

## The RevokeApiClientResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"RevokeApiClientResponseDto":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}
```

## The RotateSecretResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"RotateSecretResponseDto":{"type":"object","properties":{"clientId":{"type":"string"},"clientSecret":{"type":"string"},"message":{"type":"string"}},"required":["clientId","clientSecret","message"]}}}}
```

## The ApiClientsRequestDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"ApiClientsRequestDto":{"type":"object","properties":{"clientId":{"type":"string","description":"The API client ID provided when the API client was created"},"clientSecret":{"type":"string","description":"The API client secret provided when the API client was created"},"organizationId":{"type":"string","description":"The organization ID associated with this API client"}},"required":["clientId","clientSecret","organizationId"]}}}}
```

## The GetTokenResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"components":{"schemas":{"GetTokenResponseDto":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token to use for authenticated API requests"},"token_type":{"type":"string","description":"Type of token (always \"Bearer\")"},"expires_in":{"type":"number","description":"Token expiration time in seconds"}},"required":["token","token_type","expires_in"]}}}}
```


# DSP factsheet

Data privacy, security controls, retention, and compliance posture for Nora.

### Introduction

At Insly, we prioritize privacy and security. We follow the latest standards and compliance measures across infrastructure, processes, and product design.

### Data privacy

Insly safeguards user privacy by strictly following applicable privacy laws. Insly is the data ‘controller’ of any information provided. This information remains secure and confidential.

### Data minimization and anonymization

Only essential data is extracted to provide the requested services. Any unnecessary Personally Identifiable Information (PII) is anonymized or discarded. Insly limits data collection to the minimum required for service delivery.

### Data security practices

To meet the highest standards in data security, Insly upholds the following principles:

* Strict data silos between tenants.
* SOC 2 Type II certified identification and authentication layer.
* Role-Based Access Control (RBAC) to enforce least privilege access across all roles.
* Fully GDPR-compliant data processing and sub-processor practices.
* Agreements with AI providers to meet enterprise-grade privacy standards.

#### Database-level data security

* Robust organization-based tenancy model keeps each client’s data isolated and secure.
* Advanced database security with connection-level access control maintains strict data silos across testing and production accounts.
* AES-256 encryption over TLS 1.3 for all network traffic ensures data confidentiality and protection.

#### Access control

* Dynamic Role-Based Access Control (RBAC) adjusts to meet organizational requirements, offering multi-level permissions.
* Quarterly access audits and ad-hoc access reviews ensure adherence to the least privilege principle.
* SOC 2 Type II certified authentication for secure access.

### Purpose limitation and restricted retention

Data collected is used solely for contracted purposes.

### Transparency in data use

Insly may use aggregated and anonymized data from extracted content to improve AI models or enhance service functionality. No individual data points are identifiable. Complete confidentiality is maintained.

### Data processing and file handling agreements with LLM-related service providers

* Strict data handling agreements with LLM-related service providers mandate data deletion post-processing.
* Regular assessments of tools, including offerings by Anthropic, OpenAI, MS Azure, for compliance with privacy regulations.
* Customizable document retention period, with AES-256 encryption securing all files at rest.

### Monitoring and incident response

* Real-time monitoring with expedited response mechanisms for critical incidents.
* Regular training equips employees to handle sensitive data and recognize security risks.
* The response includes detection, containment, eradication, and recovery steps to mitigate any security incident.
* Incident response transparency: Clients are notified promptly of any data breach, including mitigation steps and timelines.

### Sub-processor transparency and accountability

For transparency, Insly provides a list of all third-party sub-processors used in data processing upon request. Each processor follows strict security protocols to ensure data protection compliance.

### User rights and data requests

Users have the right to access, correct, or delete their data. Requests can be submitted through Insly’s contact channels. Responses are provided within 30 days, subject to verification requirements.

### Compliance certifications and continuous monitoring

Insly performs regular audits and penetration tests as part of ongoing security monitoring to maintain high security standards. Automated tools and processes for compliance verification are in place.

### Client-specific data protection options

Insly offers enhanced data protection measures upon request, including additional encryption and custom data deletion options for clients with specific regulatory needs.

### Contact us

For detailed information or to report a security concern, contact:

* <info@insly.com>


