API-referentie

De Vink-API

Laat je eigen programma of automatiseringsplatform met Vink praten. Alles op deze pagina komt uit hetzelfde OpenAPI-document dat de API zelf levert.

Overzicht

Elk endpoint staat onder één basis-URL. De versie staat in het pad: /v1.

https://vink.page/v1

Verzoeken en antwoorden zijn JSON, en elke sleutel is snake_case, net als in de webhook-Payload. Id's zijn strings.

Binnen /v1 voegen we alleen toe: nieuwe endpoints, nieuwe optionele parameters en nieuwe sleutels in antwoorden. Negeer sleutels die je niet kent. Wat je code zou breken, krijgt een nieuwe versie.

Download het OpenAPI 3.1-document om een client te maken of het in een tool te importeren.

De beschrijvingen van endpoints en velden hieronder zijn in het Engels, net als de API zelf.

Stuur bij elk verzoek een API-sleutel mee. Een Admin maakt die in de app onder Instellingen → API-sleutels, geeft hem een naam en ziet hem één keer. Een sleutel hoort bij één organisatie en komt alleen bij de gegevens van die organisatie.

Authorization: Bearer vink_live_…

Behandel een sleutel als een wachtwoord: bewaar hem op je server, nooit in een browser of app. Een ontbrekende, onbekende of ingetrokken sleutel krijgt 401. Trek je één sleutel in, dan blijven je andere sleutels werken.

Een API-sleutel is voor een programma zonder gebruiker: hij stuurt Inzendingen in, leest ze en hun Deliveries, beheert Subscriptions en verstuurt een mislukte Delivery opnieuw, maar hij kan een Inzending niet wijzigen. Een AI-agent gebruikt een Agentverbinding, zie Voor AI-agents. Bij elk endpoint hieronder staat welke toegang het vraagt.

Voor AI-agents

Laat je eigen AI-agent met Vink werken: een papier insturen, de waarden lezen, verbeteren wat onzeker is en, waar jij dat toestaat, goedkeuren. De agent handelt namens jou. Wat hij wijzigt, staat op jouw naam via agent.

Een agent verbinden

Voeg Vink in je agent toe als externe MCP-server. Dat werkt met elke MCP-client die externe servers met OAuth ondersteunt, zoals Claude, ChatGPT of Cursor.

https://vink.page/mcp

De agent opent Vink. Je logt in, kiest de Organisatie en geeft toestemming. Dat is een Agentverbinding: die heeft jouw rechten in die Organisatie. Je trekt hem in onder Instellingen → Agentverbindingen. Zonder MCP roept een agent dezelfde endpoints aan met zijn OAuth-toegangstoken als Authorization: Bearer $VINK_AGENT_TOKEN.

De werkwijze

send_submission: stuur een PDF, foto, e-mail, spreadsheet of Word-bestand in, voor één Formulier of zodat Vink het Formulier kiest.
get_submission met wait (tot 25 seconden): de aanroep antwoordt zodra Vink het gelezen heeft. Nog processing? Roep hem opnieuw aan.
Lees fields: elke waarde heeft een confidence en needs_review.
correct_fields: verbeter de waarden die te controleren zijn. Een verbeterde waarde hoeft niet meer gecontroleerd te worden.
approve: alleen als het Formulier Goedkeuring door agent toestaat en er niets meer te controleren is. Anders keurt een mens het goed in Vink.

De agent heeft ook list_forms en get_form_schema om je Formulieren te lezen, change_form en reject vóór de Goedkeuring, en voor een Admin propose_form en get_form_proposal, zodat Vink de velden van een nieuw Formulier voorstelt. Een Admin heeft ook list_integrations, get_deliveries en retry_delivery: daarmee controleert de agent of een goedgekeurde Inzending in je systemen is aangekomen. get_usage toont de credits die over zijn.

Goedkeuring door agent

Een Goedkeuring stuurt de Payload naar je systemen (boekhouding, spreadsheets) en is moeilijk terug te draaien. Daarom mag een agent alleen goedkeuren bij een Formulier waar een Admin Goedkeuring door agent aanzette, en alleen als er niets op de Inzending te controleren is. Het staat standaard uit. Staat het uit, dan antwoordt approve met agent_approval_off. Zijn er nog waarden te controleren, dan met needs_review.

Voorbeeld: wachten op de waarden

Dezelfde aanroep zonder MCP. Hij wacht tot Vink de Inzending gelezen heeft, hooguit 25 seconden.

Verzoek

curl "https://vink.page/v1/submissions/j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb?wait=25" \
  -H "Authorization: Bearer $VINK_AGENT_TOKEN"

Voorbeeldantwoord

{
  "id": "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb",
  "form_id": "k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra",
  "state": "needs_review",
  "filename": "factuur-1042.pdf",
  "uploaded_at": "2026-10-06T09:00:00.000Z",
  "data_deleted_at": null,
  "fields": {
    "supplier": {
      "value": "Hoekstra Installatie",
      "confidence": 0.97,
      "needs_review": false,
      "pages": [
        1
      ]
    },
    "invoice_number": {
      "value": "F2026-0412",
      "confidence": 0.95,
      "needs_review": false,
      "pages": [
        1
      ]
    },
    "total_amount": {
      "value": 151.25,
      "confidence": 0.62,
      "needs_review": true,
      "pages": [
        1
      ]
    }
  },
  "payload": null
}

payload blijft null tot de Goedkeuring: een API-sleutel of agent krijgt de Payload pas na Goedkeuring, dezelfde die je Koppelingen krijgen.

Fouten

Een mislukt verzoek krijgt een 4xx- of 5xx-status en altijd dezelfde JSON-body. Kijk naar code; message is voor mensen en kan veranderen.

{
  "error": {
    "code": "invalid_api_key",
    "message": "This API Key doesn't exist or was revoked."
  }
}

Status	Code	Betekenis
401	missing_api_key	No `Authorization: Bearer <key>` header.
401	invalid_api_key	The key is unknown or was revoked.
401	invalid_token	The agent's OAuth access token is unknown or expired, or its Agent Connection was revoked or ended.
403	forbidden	The endpoint needs the other kind of access: an API Key (Subscriptions, Integrations, Deliveries), or an Agent Connection (changes to a Submission, Form Proposals); Form Proposals also need an Admin's Agent Connection.
404	not_found	No such endpoint, or nothing with that id in your Organisation.
500	internal_error	Something went wrong on our side. Try again later.
400	missing_file	No `file` part, or an empty body.
400	invalid_request	An email's JSON is invalid (not JSON, a wrong type, or an attachment that isn't base64), or a `reference` is over 100 characters or has a control character.
402	out_of_items	Not enough Items left for this input.
409	form_archived	The Form is archived; an Admin can restore it in Vink.
413	file_too_large	The file is larger than 10 MB.
415	unsupported_file_type	The file is none of the types Vink reads, or can't be opened.
415	not_a_pdf	The file is sent as a PDF and isn't a PDF Vink can read.
415	media_type_mismatch	The `Content-Type` names another file type than the file is.
415	unsupported_media_type	The body is none of multipart/form-data, application/json, a file type (application/pdf, image/jpeg, image/png, image/heic, message/rfc822, application/vnd.ms-outlook, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/csv) or application/octet-stream.
422	too_many_pages	The PDF has more than 20 pages.
422	too_many_attachments	The email has more than 10 attachments.
422	empty_email	The email has no text and no attachments.
422	too_many_rows	Vink reads up to 5,000 rows per Spreadsheet; this one has more.
400	invalid_request	`wait` on Get a Submission isn't a whole number of seconds.
403	agent_approval_off	An agent may approve only on a Form whose Agent Approval an Admin switched on.
409	conflict	The Submission's state rules the change out: it is approved, rejected or still being read.
409	needs_review	An agent may approve only when nothing on the Submission needs review: correct those values first.
400	invalid_request	The body isn't the JSON the endpoint takes.
409	too_many_subscriptions	The Organisation already has 50 Subscriptions.
409	form_archived	The Form is archived; an Admin can restore it in Vink.
422	invalid_url	A Subscription's `url` must be an https URL.
409	not_failed	Only a `failed` Delivery can be sent again.
409	integration_removed	The Delivery's Integration was removed or detached; it can't be sent again.
409	data_deleted	The Submission's data was deleted; there's nothing left to send.
422	invalid_description	The description is empty or longer than 2000 characters.
429	too_many_descriptions	The Organisation described 20 Forms in the last 24 hours.

Forms

The kinds of document your Organisation reads, and their Fields.

List Forms

GET/v1/forms

Toegang: API-sleutel of Agentverbinding

Every Form of the key's Organisation, with the Fields of its current version. Automation platforms use it to show your Fields as dynamic fields.

Antwoorden

Status	Beschrijving
200	The Forms.({ data: Form[] })
401	The API Key is missing, unknown or revoked.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/forms \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "data": [
    {
      "id": "k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra",
      "name": "Invoice",
      "description": "Incoming supplier invoices",
      "version": 3,
      "fields": [
        {
          "key": "supplier",
          "label": "Leverancier",
          "type": "text",
          "required": true
        },
        {
          "key": "invoice_number",
          "label": "Factuurnummer",
          "type": "text",
          "required": true
        },
        {
          "key": "invoice_date",
          "label": "Factuurdatum",
          "type": "date",
          "required": true
        },
        {
          "key": "total_amount",
          "label": "Totaalbedrag",
          "type": "number",
          "required": true
        },
        {
          "key": "currency",
          "label": "Valuta",
          "type": "choice",
          "required": false,
          "options": [
            "EUR",
            "USD"
          ]
        },
        {
          "key": "lines",
          "label": "Regels",
          "type": "list",
          "required": false,
          "fields": [
            {
              "key": "description",
              "label": "Omschrijving",
              "type": "text",
              "required": true
            },
            {
              "key": "quantity",
              "label": "Aantal",
              "type": "number",
              "required": false
            },
            {
              "key": "amount",
              "label": "Bedrag",
              "type": "number",
              "required": true
            }
          ]
        }
      ]
    }
  ]
}

Get a Form

GET/v1/forms/{id}

Toegang: API-sleutel of Agentverbinding

One Form of your Organisation, with the Fields of its current version, as in List Forms, and also its General Instruction and Guidelines: what your Organisation told Vink about reading this kind of document. You can read them here; an Editor changes them in the app.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Form's `id`, from List Forms.

Antwoorden

Status	Beschrijving
200	The Form.(FormWithInstructions)
401	The API Key is missing, unknown or revoked.(Error)
404	No Form with that id in your Organisation.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/forms/{id} \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "id": "k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra",
  "name": "Invoice",
  "description": "Incoming supplier invoices",
  "version": 3,
  "fields": [
    {
      "key": "supplier",
      "label": "Leverancier",
      "type": "text",
      "required": true
    },
    {
      "key": "invoice_number",
      "label": "Factuurnummer",
      "type": "text",
      "required": true
    },
    {
      "key": "invoice_date",
      "label": "Factuurdatum",
      "type": "date",
      "required": true
    },
    {
      "key": "total_amount",
      "label": "Totaalbedrag",
      "type": "number",
      "required": true
    },
    {
      "key": "currency",
      "label": "Valuta",
      "type": "choice",
      "required": false,
      "options": [
        "EUR",
        "USD"
      ]
    },
    {
      "key": "lines",
      "label": "Regels",
      "type": "list",
      "required": false,
      "fields": [
        {
          "key": "description",
          "label": "Omschrijving",
          "type": "text",
          "required": true
        },
        {
          "key": "quantity",
          "label": "Aantal",
          "type": "number",
          "required": false
        },
        {
          "key": "amount",
          "label": "Bedrag",
          "type": "number",
          "required": true
        }
      ]
    }
  ],
  "general_instruction": "Our supplier numbers start with LEV-. Leave a number without it empty.",
  "guidelines": [
    {
      "name": "Credit notes",
      "use_when": "The document is a credit note",
      "instruction": "Write the total as a negative amount.",
      "field_keys": [
        "total_amount"
      ]
    }
  ]
}

Submissions

PDFs, photos, emails, Spreadsheets and Word Files Vink reads into a Form's Fields.

Send a Submission in, without choosing the Form

POST/v1/submissions

Toegang: API-sleutel of Agentverbinding

Sends a PDF, a photo (JPG, PNG, HEIC) or an email in, exactly as if it was uploaded in the app: the same checks, the same Items counted once, and it shows in Vink with the API Key's name as its source. Without form_id, Vink reads it and picks the Form from your Organisation's Forms; a Submission that fits none waits under No Form (state: no_form in Get a Submission). With form_id, it is read with that Form, as on Send a Submission in. A PDF is at most 20 pages and 10 MB, an image 10 MB, an email's text 200 KB with at most 10 attachments of 12 MB together. Your Organisation must have enough Items left: a PDF costs its pages, a photo 1, an email its text (1, when it has any) plus each attachment; an email file (.eml) is split as mail to an Intake Address is, into one Submission or one per paper (id is the first), and a text that is only a cover note costs nothing.

Parameters

Naam	Type	Beschrijving
form_id	string	The Form's `id`, from List Forms. Left out, Vink picks the Form. It can also be a `form_id` part of a multipart body or a `form_id` property of an email's JSON.
filename	string	The name the Submission shows in Vink. Defaults to the multipart file's name, else `document.pdf` (`.jpg`, `.png`, `.heic`, `.docx`, `.xlsx`, `.csv`) by what the file is, else an email's subject.
reference	string	Your own id for this input, such as an order number or a case id: 1 to 100 characters, no line breaks or other control characters. Vink keeps it on every Submission the input becomes, shows it in review, and sends it as `submission.reference` in each Delivery and in Get a Submission. Left out or empty: no Reference. A `reference` part of a multipart body, or a `reference` property of an email's JSON, comes before this one.

Body van het verzoek

The file or the email, with a request body of at most 10 MB in total. A file is a PDF, a JPG, PNG or HEIC image, an email file (message/rfc822 .eml, or Outlook's application/vnd.ms-outlook .msg), a Word File (.docx) or a Spreadsheet of up to 5,000 rows (.xlsx, or a text/csv .csv with ;, , or tab between the fields): send it as multipart/form-data with the file in a part named file (an optional filename part names it, an optional form_id part picks the Form, an optional reference part is your own id for it), or as the body itself. Vink decides what the file is from its first bytes (a CSV, which has none, by its Content-Type or its name). A Content-Type that names one of these types and contradicts the bytes is refused (media_type_mismatch); application/octet-stream or a part without a type leaves it to the bytes. An email can also be sent as application/json (see EmailSubmission): its text and up to 10 attachments of the file types above, base64-encoded.

Antwoorden

Status	Beschrijving
201	Vink accepted the file or email and is reading it.(SentSubmission)
400	The request has no file in it (`missing_file`), or an email body or a `reference` isn't valid (`invalid_request`).(Error)
401	The API Key is missing, unknown or revoked.(Error)
402	Your Organisation has fewer Items left than the input needs.(Error)
404	A `form_id` was given, and no Form in your Organisation has it.(Error)
409	The Form is archived. An Admin can restore it in Vink.(Error)
413	The request body, an image, a Word File, a Spreadsheet or an email's text or attachments are over their limit.(Error)
415	Vink can't read the file. `unsupported_file_type`: it is none of the file types above (or an email, Word File or Spreadsheet that can't be opened). `not_a_pdf`: it is sent as a PDF and isn't a PDF Vink can read. `media_type_mismatch`: the `Content-Type` names another file type than the bytes. `unsupported_media_type`: the body is none of the content types above.(Error)
422	The PDF has more than 20 pages (`too_many_pages`), an email has more than 10 attachments (`too_many_attachments`) or no text and no attachments (`empty_email`), or a Spreadsheet has more than 5,000 rows (`too_many_rows`).(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X POST https://vink.page/v1/submissions \
  -H "Authorization: Bearer $VINK_API_KEY" \
  -F "[email protected]"

Voorbeeldantwoord

{
  "id": "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb",
  "ids": [
    "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb"
  ],
  "state": "processing"
}

Send a Submission in

POST/v1/forms/{form_id}/submissions

Toegang: API-sleutel of Agentverbinding

Sends a PDF, a photo (JPG, PNG, HEIC) or an email to a Form. It becomes a Submission exactly as if it was uploaded in the app: the same checks, the same Items counted once, and it shows in Vink with the API Key's name as its source. Vink then reads it; the Submission needs review or is approved later. A PDF is at most 20 pages and 10 MB, an image 10 MB, an email's text 200 KB with at most 10 attachments of 12 MB together. Your Organisation must have enough Items left: a PDF costs its pages, a photo 1, an email its text (1, when it has any) plus each attachment; an email file (.eml) is split as mail to an Intake Address is, into one Submission or one per paper (id is the first), and a text that is only a cover note costs nothing. To let Vink pick the Form, use Send a Submission in, without choosing the Form.

Parameters

Naam	Type	Beschrijving
form_idverplicht	string	The Form's `id`, from List Forms.
filename	string	The name the Submission shows in Vink. Defaults to the multipart file's name, else `document.pdf` (`.jpg`, `.png`, `.heic`, `.docx`, `.xlsx`, `.csv`) by what the file is, else an email's subject.
reference	string	Your own id for this input, such as an order number or a case id: 1 to 100 characters, no line breaks or other control characters. Vink keeps it on every Submission the input becomes, shows it in review, and sends it as `submission.reference` in each Delivery and in Get a Submission. Left out or empty: no Reference. A `reference` part of a multipart body, or a `reference` property of an email's JSON, comes before this one.

Body van het verzoek

The file or the email, with a request body of at most 10 MB in total. A file is a PDF, a JPG, PNG or HEIC image, an email file (message/rfc822 .eml, or Outlook's application/vnd.ms-outlook .msg), a Word File (.docx) or a Spreadsheet of up to 5,000 rows (.xlsx, or a text/csv .csv with ;, , or tab between the fields): send it as multipart/form-data with the file in a part named file (an optional filename part names it, an optional reference part is your own id for it), or as the body itself. Vink decides what the file is from its first bytes (a CSV, which has none, by its Content-Type or its name). A Content-Type that names one of these types and contradicts the bytes is refused (media_type_mismatch); application/octet-stream or a part without a type leaves it to the bytes. An email can also be sent as application/json (see EmailSubmission): its text and up to 10 attachments of the file types above, base64-encoded.

Antwoorden

Status	Beschrijving
201	Vink accepted the file or email and is reading it.(SentSubmission)
400	The request has no file in it (`missing_file`), or an email body or a `reference` isn't valid (`invalid_request`).(Error)
401	The API Key is missing, unknown or revoked.(Error)
402	Your Organisation has fewer Items left than the input needs.(Error)
404	No Form with this id in your Organisation.(Error)
409	The Form is archived. An Admin can restore it in Vink.(Error)
413	The request body, an image, a Word File, a Spreadsheet or an email's text or attachments are over their limit.(Error)
415	Vink can't read the file. `unsupported_file_type`: it is none of the file types above (or an email, Word File or Spreadsheet that can't be opened). `not_a_pdf`: it is sent as a PDF and isn't a PDF Vink can read. `media_type_mismatch`: the `Content-Type` names another file type than the bytes. `unsupported_media_type`: the body is none of the content types above.(Error)
422	The PDF has more than 20 pages (`too_many_pages`), an email has more than 10 attachments (`too_many_attachments`) or no text and no attachments (`empty_email`), or a Spreadsheet has more than 5,000 rows (`too_many_rows`).(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X POST https://vink.page/v1/forms/{form_id}/submissions \
  -H "Authorization: Bearer $VINK_API_KEY" \
  -F "[email protected]"

Voorbeeldantwoord

{
  "id": "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb",
  "ids": [
    "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb"
  ],
  "state": "processing"
}

Get a Submission

GET/v1/submissions/{id}

Toegang: API-sleutel of Agentverbinding

The Submission's state, its Field Values once Vink has read them, and, once it is approved, its Payload: the same envelope every Webhook gets. fields is there before Approval, with each value's Confidence and whether it is Needs Review, so you can work with the values at once. payload is null until Approval. After its data is deleted (Retention, or an Admin's delete now) fields and payload are null and data_deleted_at says when.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Submission's id, from Send in a Submission or an envelope's `submission.id`.
wait	integer	Seconds to hold the request while the Submission is `processing`. It answers as soon as the state leaves `processing`, or when the seconds are up, with the Submission as it is then (that can still be `processing`). At most 25: a larger value waits 25. Left out or `0`, it answers at once; polling without `wait` works as well.

Antwoorden

Status	Beschrijving
200	The Submission.(Submission)
400	`wait` isn't a whole number of seconds.(Error)
401	The API Key is missing, unknown or revoked.(Error)
404	No Submission with that id in your Organisation.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/submissions/{id} \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "id": "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb",
  "form_id": "k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra",
  "state": "approved",
  "filename": "factuur-1042.pdf",
  "reference": "PO-2026-1042",
  "uploaded_at": "2026-10-06T09:00:00.000Z",
  "data_deleted_at": null,
  "fields": {
    "supplier": {
      "value": "Hoekstra Installatie",
      "confidence": 0.97,
      "needs_review": false,
      "pages": [
        1
      ]
    },
    "invoice_number": {
      "value": "F2026-0412",
      "confidence": 0.95,
      "needs_review": false,
      "pages": [
        1
      ]
    },
    "invoice_date": {
      "value": "2026-10-02",
      "confidence": 0.93,
      "needs_review": false,
      "pages": [
        1
      ]
    },
    "total_amount": {
      "value": 151.25,
      "confidence": 0.91,
      "needs_review": false,
      "pages": [
        1
      ]
    },
    "currency": {
      "value": "EUR",
      "confidence": 0.98,
      "needs_review": false,
      "pages": [
        1
      ]
    },
    "lines": {
      "needs_review": false,
      "entries": [
        {
          "description": {
            "value": "Kopieerpapier A4",
            "confidence": 0.96,
            "needs_review": false,
            "pages": [
              1
            ]
          },
          "quantity": {
            "value": 5,
            "confidence": 0.94,
            "needs_review": false,
            "pages": [
              1
            ]
          },
          "amount": {
            "value": 125,
            "confidence": 0.92,
            "needs_review": false,
            "pages": [
              1
            ]
          }
        }
      ]
    }
  },
  "payload": {
    "event": "submission.approved",
    "delivery_id": "sub_j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb",
    "test": false,
    "submission": {
      "id": "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb",
      "filename": "factuur-1042.pdf",
      "reference": "PO-2026-1042",
      "uploaded_at": "2026-10-06T09:00:00.000Z",
      "file_url": "https://files.vink.page/factuur-1042.pdf?X-Amz-Expires=86400&X-Amz-Signature=…"
    },
    "form": {
      "id": "k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra",
      "version": 3
    },
    "approval": {
      "mode": "manual",
      "by": "user_2x9KqL",
      "at": "2026-10-06T09:12:00.000Z"
    },
    "data": {
      "supplier": "Hoekstra Installatie",
      "invoice_number": "F2026-0412",
      "invoice_date": "2026-10-02",
      "total_amount": 151.25,
      "currency": "EUR",
      "lines": [
        {
          "description": "Kopieerpapier A4",
          "quantity": 5,
          "amount": 125
        }
      ]
    }
  }
}

Correct Field Values

PATCH/v1/submissions/{id}/fields

Toegang: Alleen Agentverbinding

Corrects one or more Field Values of a Submission in needs_review, all or none. Name a value by its path in fields of Get a Submission: a Field's key (invoice_number), or for a List Field the entry's place in entries, from 0, and the sub-Field's key (lines[0].quantity). A value must fit its Field's type: a number for a number Field, yyyy-mm-dd for a date, one of the options for a choice. A corrected value no longer needs review, and the Submission is never sent by Auto-Send afterwards. Needs an Agent Connection: an agent's OAuth access token, sent as Authorization: Bearer <token>. An API Key gets 403 forbidden, since a key has no user to answer for the change. The change is the connection's user's, recorded as theirs via agent, with the same rules as in Vink.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Submission's id.

Body van het verzoek

Antwoorden

Status	Beschrijving
200	The Submission after the change, as Get a Submission answers.(Submission)
400	The body isn't `values`, a path names no value, or a value doesn't fit its Field.(Error)
401	The API Key is missing, unknown or revoked.(Error)
403	Sent with an API Key.(Error)
404	No Submission with that id in your Organisation.(Error)
409	The Submission's state rules the change out.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X PATCH https://vink.page/v1/submissions/{id}/fields \
  -H "Authorization: Bearer $VINK_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"values":{"invoice_number":"F2026-0412","lines[0].quantity":5}}'

Change a Submission's Form

POST/v1/submissions/{id}/form

Toegang: Alleen Agentverbinding

Moves a Submission to another Form before Approval, also out of no_form or failed. Its values and corrections for the old Form are dropped and Vink reads it again for the new one, so it is processing until that ends. Its Items were counted when it came in; a move counts none. Needs an Agent Connection: an agent's OAuth access token, sent as Authorization: Bearer <token>. An API Key gets 403 forbidden, since a key has no user to answer for the change. The change is the connection's user's, recorded as theirs via agent, with the same rules as in Vink.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Submission's id.

Body van het verzoek

Antwoorden

Status	Beschrijving
200	The Submission after the change, as Get a Submission answers.(Submission)
400	The body has no `form_id`.(Error)
401	The API Key is missing, unknown or revoked.(Error)
403	Sent with an API Key.(Error)
404	No Submission, or no Form, with that id in your Organisation.(Error)
409	The Submission's state rules the change out (`conflict`), or the Form is archived (`form_archived`).(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X POST https://vink.page/v1/submissions/{id}/form \
  -H "Authorization: Bearer $VINK_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"form_id":"k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra"}'

Reject a Submission

POST/v1/submissions/{id}/reject

Toegang: Alleen Agentverbinding

Rules a Submission in needs_review, failed or no_form unusable: it becomes rejected, with the reason, if any. A user can reopen it in Vink. Needs an Agent Connection: an agent's OAuth access token, sent as Authorization: Bearer <token>. An API Key gets 403 forbidden, since a key has no user to answer for the change. The change is the connection's user's, recorded as theirs via agent, with the same rules as in Vink.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Submission's id.

Body van het verzoek

Antwoorden

Status	Beschrijving
200	The Submission after the change, as Get a Submission answers.(Submission)
400	The body isn't JSON, or `reason` isn't a string.(Error)
401	The API Key is missing, unknown or revoked.(Error)
403	Sent with an API Key.(Error)
404	No Submission with that id in your Organisation.(Error)
409	The Submission's state rules the change out.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X POST https://vink.page/v1/submissions/{id}/reject \
  -H "Authorization: Bearer $VINK_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Duplicate of F2026-0411"}'

Approve a Submission

POST/v1/submissions/{id}/approve

Toegang: Alleen Agentverbinding

Approves a Submission in needs_review, which sends its Payload to the Form's Integrations. An agent may approve only when an Admin has switched on Agent Approval for the Form and nothing on the Submission needs review: correct the values that do first. The Approval is the connection's user's, with approval.mode agent in the Payload. Needs an Agent Connection: an agent's OAuth access token, sent as Authorization: Bearer <token>. An API Key gets 403 forbidden, since a key has no user to answer for the change. The change is the connection's user's, recorded as theirs via agent, with the same rules as in Vink.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Submission's id.

Antwoorden

Status	Beschrijving
200	The Submission after the change, as Get a Submission answers.(Submission)
401	The API Key is missing, unknown or revoked.(Error)
403	Sent with an API Key, or Agent Approval is off for the Form.(Error)
404	No Submission with that id in your Organisation.(Error)
409	Values still need review (`needs_review`), or the Submission's state rules the Approval out (`conflict`).(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X POST https://vink.page/v1/submissions/{id}/approve \
  -H "Authorization: Bearer $VINK_AGENT_TOKEN"

Subscriptions

For automation platforms (Zapier, Make, Power Automate): hear about a Form's Approvals. A Subscription is a Webhook in Vink, so Admins see it under Integrations.

Subscribe to Approvals

POST/v1/subscriptions

Toegang: Alleen API-sleutel

From now on, every Approval of a Submission of this Form is POSTed to url as an envelope, the same one every Webhook gets: with retries, a log in Vink and the X-Vink-Signature header. Vink makes a Webhook for it, named after the API Key and attached to the Form, so the Form's Field keys are locked while the Subscription is active. It ends when you unsubscribe, when the API Key is revoked or when an Admin deletes that Webhook.

Body van het verzoek

JSON with form_id, the Form to hear about (from List Forms), and url, the https URL that receives the envelopes.

Antwoorden

Status	Beschrijving
201	The Subscription.(Subscription)
400	The body isn't JSON with `form_id` and `url`.(Error)
401	The API Key is missing, unknown or revoked.(Error)
404	No Form with that id in your Organisation.(Error)
409	The Organisation already has 50 Subscriptions (`too_many_subscriptions`), or the Form is archived (`form_archived`).(Error)
422	`url` isn't an https URL.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X POST https://vink.page/v1/subscriptions \
  -H "Authorization: Bearer $VINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form_id":"k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra","url":"https://hooks.zapier.com/hooks/standard/123456/abcdef/"}'

Voorbeeldantwoord

{
  "id": "j57a2x9kq4m1c8v3n6e5w4t8hs7bm2rb",
  "form_id": "k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra",
  "url": "https://hooks.zapier.com/hooks/standard/123456/abcdef/",
  "created_at": "2026-10-06T09:00:00.000Z"
}

Unsubscribe

DELETE/v1/subscriptions/{id}

Toegang: Alleen API-sleutel

Ends the Subscription and removes its Webhook. Any API Key of the Organisation can end it. Approvals that are still being sent to it are given up. Idempotent: a Subscription that has ended already (an Admin deleted its Webhook, or its url answered 410), or an id Vink doesn't know, gets the same answer and nothing changes.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Subscription's id.

Antwoorden

Status	Beschrijving
200	The Subscription ended, or had ended already.(DeletedSubscription)
401	The API Key is missing, unknown or revoked.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X DELETE https://vink.page/v1/subscriptions/{id} \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "id": "j57a2x9kq4m1c8v3n6e5w4t8hs7bm2rb",
  "deleted": true
}

Sample envelope

GET/v1/forms/{form_id}/sample

Toegang: API-sleutel of Agentverbinding

An example of the envelope a Subscription receives for this Form, with example values for the Fields of its current version: what a test-send sends. Lists are arrays with one entry. Automation platforms use it to show the fields before the first real Approval.

Parameters

Naam	Type	Beschrijving
form_idverplicht	string	The Form's id, from List Forms.

Antwoorden

Status	Beschrijving
200	The example envelope, with `"test": true`.(Envelope)
401	The API Key is missing, unknown or revoked.(Error)
404	No Form with that id in your Organisation.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/forms/{form_id}/sample \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "event": "submission.approved",
  "delivery_id": "test_3f2a7c1e-9b4d-4e8a-a1f0-6c5d2b7e9a10",
  "test": true,
  "submission": {
    "id": "test",
    "filename": "example.pdf",
    "reference": null,
    "uploaded_at": "2026-10-06T09:00:00.000Z",
    "file_url": null
  },
  "form": {
    "id": "k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra",
    "version": 3
  },
  "approval": {
    "mode": "manual",
    "by": null,
    "at": "2026-10-06T09:00:00.000Z"
  },
  "data": {
    "supplier": "Example Leverancier",
    "invoice_number": "Example Factuurnummer",
    "invoice_date": "2026-01-31",
    "total_amount": 123.45,
    "currency": "EUR",
    "lines": [
      {
        "description": "Example Omschrijving",
        "quantity": 123.45,
        "amount": 123.45
      }
    ]
  }
}

Envelope schema

GET/v1/forms/{form_id}/schema

Toegang: API-sleutel of Agentverbinding

The JSON Schema of the envelope a Subscription receives for this Form, with one property per Field of its current version under data. Power Automate uses it to show your Fields as dynamic content.

Parameters

Naam	Type	Beschrijving
form_idverplicht	string	The Form's id, from List Forms.

Antwoorden

Status	Beschrijving
200	The schema.(EnvelopeSchema)
401	The API Key is missing, unknown or revoked.(Error)
404	No Form with that id in your Organisation.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/forms/{form_id}/schema \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "schema": {
    "type": "object",
    "properties": {
      "event": {
        "type": "string",
        "x-ms-summary": "Event"
      },
      "data": {
        "type": "object",
        "x-ms-summary": "Data",
        "properties": {
          "supplier": {
            "type": "string",
            "title": "Leverancier",
            "x-ms-summary": "Leverancier",
            "x-nullable": true
          }
        }
      }
    }
  }
}

Integrations

Where Vink sends a Form's Approvals: a Webhook, a Google Sheet or an Excel workbook. Admins make and change them in Vink; the API only lists them, so you can read their Deliveries.

List Integrations

GET/v1/integrations

Toegang: API-sleutel of Agentverbinding

Every Integration of the caller's Organisation, with the Forms it is attached to. Nothing of its configuration is in the answer: no URL, headers, secrets or sheet link. A Subscription is a Webhook too, so it is listed with its subscription_id.

Antwoorden

Status	Beschrijving
200	The Integrations.({ data: Integration[] })
401	The API Key is missing, unknown or revoked.(Error)
403	An Agent Connection whose user is not an Admin.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/integrations \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "data": [
    {
      "id": "m27d4x8kq2n1c9v3b6e5w4t8hs7bm2rc",
      "name": "Bookkeeping",
      "kind": "webhook",
      "form_ids": [
        "k17c9z1fx3q8d2v0n6e5w4t8hs7bm2ra"
      ],
      "subscription_id": null,
      "needs_reconnect": false
    }
  ]
}

Deliveries

One Delivery sends one approved Submission's Payload to one Integration, with retries for about 8 hours. Read the Deliveries of a Submission or of an Integration, and send a failed one again, as an Admin can with Send again in Vink.

List an Integration's Deliveries

GET/v1/integrations/{id}/deliveries

Toegang: API-sleutel of Agentverbinding

The Integration's Deliveries, newest first, a page at a time. Pass next_cursor as cursor to get the next page; it is null on the last one. With state, a page can hold fewer than limit Deliveries, even none: keep going while next_cursor isn't null.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Integration's `id`, from List Integrations.
limit	integer	How many Deliveries a page holds at most. 50 when left out.
cursor	string	The `next_cursor` of the page before. Left out, you get the first page.
state	"pending" \| "retrying" \| "delivered" \| "failed"	Only Deliveries in this state, e.g. `failed` to find what to send again.

Antwoorden

Status	Beschrijving
200	A page of Deliveries.(DeliveryList)
400	`limit`, `cursor` or `state` isn't one Vink takes.(Error)
401	The API Key is missing, unknown or revoked.(Error)
403	An Agent Connection whose user is not an Admin.(Error)
404	No Integration with that id in your Organisation.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/integrations/{id}/deliveries \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "data": [
    {
      "id": "n37e5x7kq1m2c8v3b6e5w4t8hs7bm2rd",
      "delivery_id": "dlv_5c1e2a7f-3b9d-4f8a-b1e0-7d6c2a9e8b41",
      "submission_id": "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb",
      "integration_id": "m27d4x8kq2n1c9v3b6e5w4t8hs7bm2rc",
      "integration_name": "Bookkeeping",
      "state": "failed",
      "failure_reason": "The receiver refused it (422)",
      "next_attempt_at": null,
      "can_retry": true,
      "created_at": "2026-10-06T09:00:00.000Z",
      "attempts": [
        {
          "at": "2026-10-06T09:00:01.000Z",
          "status": 422,
          "error": null,
          "body": "{\"error\":\"unknown supplier\"}"
        }
      ]
    }
  ],
  "next_cursor": null
}

List a Submission's Deliveries

GET/v1/submissions/{id}/deliveries

Toegang: API-sleutel of Agentverbinding

One Delivery per Integration the Submission's Form was attached to at Approval, oldest first. Empty before Approval, and when nothing was attached.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Submission's `id`, from Send a Submission in.

Antwoorden

Status	Beschrijving
200	The Deliveries.({ data: Delivery[] })
401	The API Key is missing, unknown or revoked.(Error)
403	An Agent Connection whose user is not an Admin.(Error)
404	No Submission with that id in your Organisation.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/submissions/{id}/deliveries \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "data": [
    {
      "id": "n37e5x7kq1m2c8v3b6e5w4t8hs7bm2rd",
      "delivery_id": "dlv_5c1e2a7f-3b9d-4f8a-b1e0-7d6c2a9e8b41",
      "submission_id": "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb",
      "integration_id": "m27d4x8kq2n1c9v3b6e5w4t8hs7bm2rc",
      "integration_name": "Bookkeeping",
      "state": "failed",
      "failure_reason": "The receiver refused it (422)",
      "next_attempt_at": null,
      "can_retry": true,
      "created_at": "2026-10-06T09:00:00.000Z",
      "attempts": [
        {
          "at": "2026-10-06T09:00:01.000Z",
          "status": 422,
          "error": null,
          "body": "{\"error\":\"unknown supplier\"}"
        }
      ]
    }
  ]
}

Send a Delivery again

POST/v1/deliveries/{id}/retry

Toegang: API-sleutel of Agentverbinding

Sends a failed Delivery again, with the same delivery_id and the Integration's configuration as it is now: a new series of up to 6 attempts, the same as Send again in Vink. It doesn't change the Submission. Only a Delivery with can_retry: true can be sent again; read it again later to see how it went.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The Delivery's `id`, from a list of Deliveries.

Antwoorden

Status	Beschrijving
202	The Delivery, now `pending`: it is sent in a moment.(Delivery)
401	The API Key is missing, unknown or revoked.(Error)
403	An Agent Connection whose user is not an Admin.(Error)
404	No Delivery with that id in your Organisation.(Error)
409	It can't be sent again: it isn't `failed` (`not_failed`), its Integration was removed (`integration_removed`), or its Submission's data was deleted (`data_deleted`).(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X POST https://vink.page/v1/deliveries/{id}/retry \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "id": "n37e5x7kq1m2c8v3b6e5w4t8hs7bm2rd",
  "delivery_id": "dlv_5c1e2a7f-3b9d-4f8a-b1e0-7d6c2a9e8b41",
  "submission_id": "j57b2x0sd4kq9r1m8n3c6v7w5h7bm2rb",
  "integration_id": "m27d4x8kq2n1c9v3b6e5w4t8hs7bm2rc",
  "integration_name": "Bookkeeping",
  "state": "pending",
  "failure_reason": null,
  "next_attempt_at": null,
  "can_retry": false,
  "created_at": "2026-10-06T09:00:00.000Z",
  "attempts": [
    {
      "at": "2026-10-06T09:00:01.000Z",
      "status": 422,
      "error": null,
      "body": "{\"error\":\"unknown supplier\"}"
    }
  ]
}

Form Proposals

Fields Vink proposes for a new Form, from a sample or a description. For agents only: an Admin saves a proposal as a Form in the app.

Propose a Form

POST/v1/form-proposals

Toegang: Alleen Agentverbinding

Vink proposes Fields for a new Form from one sample (a PDF, a photo or an email, sent the same ways as Send a Submission in) or from a description in words, exactly as an Admin does in the app. Only through an Agent Connection whose user is an Admin; the proposal is that user's, made via agent. A sample costs its Items once, as a Submission does; a description costs no Items, and an Organisation can describe at most 20 Forms in 24 hours. Poll Get a Form Proposal until it is ready. No endpoint saves a proposal as a Form: an Admin does that in the app. An unsaved proposal is deleted after 7 days.

Body van het verzoek

A sample file, with the same bodies and limits as Send a Submission in (form_id is not used), or application/json: either { "description": "…" } (at most 2000 characters: what the document is and which data you need) or an email (EmailSubmission).

Antwoorden

Status	Beschrijving
201	Vink is reading the sample or the description and proposing Fields.(CreatedFormProposal)
400	The request has no file in it (`missing_file`), or the JSON isn't valid (`invalid_request`).(Error)
401	The API Key is missing, unknown or revoked.(Error)
402	Your Organisation has fewer Items left than the sample needs.(Error)
403	Form Proposals are made by a user who is an Admin: an API Key, or an agent whose user is a Member, can't make or read them.(Error)
413	The request body, an image or an email's text or attachments are over their limit.(Error)
415	Vink can't read the sample: the same codes as Send a Submission in.(Error)
422	The description is empty or too long (`invalid_description`), or the sample is refused as on Send a Submission in (`too_many_pages`, `too_many_attachments`, `empty_email`, `too_many_rows`).(Error)
429	Your Organisation described 20 Forms in the last 24 hours.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl -X POST https://vink.page/v1/form-proposals \
  -H "Authorization: Bearer $VINK_AGENT_TOKEN" \
  -F "[email protected]"

Voorbeeldantwoord

{
  "id": "m81d4f2ty6p0c3x9b5a7k2w4hs7bm2rc",
  "state": "processing"
}

Get a Form Proposal

GET/v1/form-proposals/{id}

Toegang: Alleen Agentverbinding

The proposal's state and, once it is ready, the proposed Fields in the shape of List Forms. Only through an Agent Connection whose user is an Admin.

Parameters

Naam	Type	Beschrijving
idverplicht	string	The proposal's id, from Propose a Form.

Antwoorden

Status	Beschrijving
200	The Form Proposal.(FormProposal)
401	The API Key is missing, unknown or revoked.(Error)
403	Form Proposals are made by a user who is an Admin: an API Key, or an agent whose user is a Member, can't make or read them.(Error)
404	No Form Proposal with that id in your Organisation. It may be saved, discarded, or deleted after 7 days.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/form-proposals/{id} \
  -H "Authorization: Bearer $VINK_AGENT_TOKEN"

Voorbeeldantwoord

{
  "id": "m81d4f2ty6p0c3x9b5a7k2w4hs7bm2rc",
  "state": "ready",
  "source": "sample",
  "filename": "factuur-1042.pdf",
  "description": null,
  "failure": null,
  "created_at": "2026-10-12T09:00:00.000Z",
  "fields": [
    {
      "key": "invoice_number",
      "label": "Factuurnummer",
      "type": "text",
      "required": false,
      "recommended": true
    },
    {
      "key": "total_amount",
      "label": "Totaalbedrag",
      "type": "number",
      "required": false,
      "recommended": true
    },
    {
      "key": "supplier_iban",
      "label": "IBAN",
      "type": "text",
      "required": false,
      "recommended": false
    }
  ]
}

Usage

The Credits your Organisation has left this period. One PDF page, email, photo, Spreadsheet or Word File costs 10 Credits.

Get usage

GET/v1/usage

Toegang: API-sleutel of Agentverbinding

The Organisation's Plan, the Credits left and used this period, and when they reset.

Antwoorden

Status	Beschrijving
200	The usage.(Usage)
401	The API Key is missing, unknown or revoked.(Error)
500	Something went wrong on our side.(Error)

Verzoek

curl https://vink.page/v1/usage \
  -H "Authorization: Bearer $VINK_API_KEY"

Voorbeeldantwoord

{
  "plan": "team",
  "unlimited": false,
  "credits_left": 4210,
  "credits_used": 1790,
  "resets_at": "2026-11-12T00:00:00.000Z"
}

Objecten

De objecten die de endpoints teruggeven.

Error

Naam	Type	Beschrijving
errorverplicht	{ code: string, message: string }

Form

Naam	Type	Beschrijving
idverplicht	string	Use it in the Form's other endpoints.
nameverplicht	string
descriptionverplicht	string \| null
versionverplicht	integer	Goes up by one every time the Form is saved.
fieldsverplicht	Field[]

FormWithInstructions

Naam	Type	Beschrijving
idverplicht	string	Use it in the Form's other endpoints.
nameverplicht	string
descriptionverplicht	string \| null
versionverplicht	integer	Goes up by one every time the Form is saved.
fieldsverplicht	Field[]
general_instructionverplicht	string	Vink follows it on every Submission of this Form, under its own fixed rules. Empty when there is none.
guidelinesverplicht	Guideline[]	Instructions for one situation each, at most 20.

Guideline

Naam	Type	Beschrijving
nameverplicht	string	Unique within the Form.
use_whenverplicht	string	When it applies, in words: Vink uses the Guideline on a Submission only when this fits the document. Empty: always.
instructionverplicht	string
field_keysverplicht	string[]	The keys of the Fields it is about; a List Field's key covers its sub-Fields. Empty: all Fields.

Field

Naam	Type	Beschrijving
keyverplicht	string	The Field's name in the Payload, snake_case.
labelverplicht	string	What users see in Vink.
typeverplicht	"text" \| "number" \| "date" \| "boolean" \| "choice" \| "list"	`choice` has `options`; `list` has `fields`, the sub-Fields of each entry.
requiredverplicht	boolean
options	string[]	Only on `choice`: the values the Payload can hold.
fields	SubField[]	Only on `list`: the sub-Fields of each entry.

SubField

Naam	Type	Beschrijving
keyverplicht	string	The Field's name in the Payload, snake_case.
labelverplicht	string	What users see in Vink.
typeverplicht	"text" \| "number" \| "date" \| "boolean" \| "choice"	`choice` has `options`.
requiredverplicht	boolean
options	string[]	Only on `choice`: the values the Payload can hold.

SentSubmission

Naam	Type	Beschrijving
idverplicht	string	The Submission's id: the first one, when there are more.
idsverplicht	string[]	Every Submission the input became. More than one only for an email file that Vink split, as mail to an Intake Address is.
stateverplicht	"processing"	Always `processing` here: Vink is reading the file or email.

EmailSubmission

An email as JSON. At least one of body and attachments is needed. Vink reads it as one Submission: its text, then its attachments.

Naam	Type	Beschrijving
subject	string	The subject. It names the Submission in Vink.
from	string	The sender, for example `Name <[email protected]>`.
date	string	When the email was sent.
body	string	The email's text, at most 200 KB.
attachments	{ filename: string, content_base64: string }[]	PDF, JPG, PNG or HEIC files, at most 10 and 12 MB together before base64. Any other type is refused.
form_id	string \| null	The Form's `id`. Left out or `null`, Vink picks the Form. Not used on the Form's own path.
filename	string	The name the Submission shows in Vink, instead of the subject.
reference	string \| null	Your own id for this input, such as an order number or a case id: 1 to 100 characters, no line breaks or other control characters. Vink keeps it on every Submission the input becomes, shows it in review, and sends it as `submission.reference` in each Delivery and in Get a Submission. Left out or empty: no Reference.

Submission

Naam	Type	Beschrijving
idverplicht	string
form_idverplicht	string \| null	The Form it is read with; `null` while the Router has not picked one, and in `no_form`.
stateverplicht	"processing" \| "needs_review" \| "approved" \| "rejected" \| "failed" \| "no_form" \| "deleted"	`processing`: being read. `needs_review`: waits for a user to check it. `approved`: approved; the Payload is here until its data is deleted. `rejected`: a user ruled it unusable. `failed`: Vink couldn't read it. `no_form`: Vink read it, but none of your Forms fits; a user can move it to a Form. `deleted`: its data was deleted before Approval. Only `approved` ever has a Payload.
filenameverplicht	string
referenceverplicht	string \| null	Your own id for it (an order number, a case id), sent as `reference` to Send a Submission in or as the plus-tag of an Intake Address (`<address>+po123@…`, in lower case). `null` when none came with it.
uploaded_atverplicht	string
data_deleted_atverplicht	string \| null	When its file and values were deleted; `null` while they are kept.
fieldsverplicht	object \| null	The Field Values, readable before Approval: one key per Field of the Form, in the Form's order. A Field is a FieldValue, a List Field a ListFieldValue. They include a user's corrections. `null` while it is `processing`, `failed`, `no_form` or `deleted`, and after the data is deleted. The Payload stays `null` until Approval.
payloadverplicht	Envelope \| null	The envelope a Webhook gets, with `delivery_id` `sub_<id>`. `null` before Approval and after the data is deleted.

FieldValue

One Field's value as Vink read it, or as a user corrected it.

Naam	Type	Beschrijving
valueverplicht	string \| number \| boolean \| null	`null` for no value.
confidenceverplicht	number \| null	How sure Vink is of the value, from 0 to 1; `null` when Vink stored no value for the Field.
needs_reviewverplicht	boolean	`true` while a user must still check the value.
pagesverplicht	integer[]	The pages the value was read on, from 1; `[]` for none.

ListFieldValue

A List Field's entries; entries a user removed are left out, entries a user added are in.

Naam	Type	Beschrijving
needs_reviewverplicht	boolean	`true` while a user must still confirm the entries are complete.
entriesverplicht	object[]	One object per entry, with a FieldValue per sub-Field key; `[]` for none.

EnvelopeSchema

Naam	Type	Beschrijving
schemaverplicht	object	A JSON Schema of the envelope, in Swagger 2.0 style: one `type` per property, `x-nullable: true` where the value can be `null`, and each Field's label as `title` and `x-ms-summary`.

SubscriptionRequest

Naam	Type	Beschrijving
form_idverplicht	string	The Form whose Approvals you want.
urlverplicht	string	Receives the envelopes. https only.

Subscription

Naam	Type	Beschrijving
idverplicht	string	Use it to unsubscribe.
form_idverplicht	string
urlverplicht	string
created_atverplicht	string

DeletedSubscription

Naam	Type	Beschrijving
idverplicht	string
deletedverplicht	boolean	Always `true`.

Envelope

What every Webhook receives on an Approval, signed with X-Vink-Signature.

Naam	Type	Beschrijving
eventverplicht	"submission.approved"
delivery_idverplicht	string	The same on every retry and re-send of one Delivery: de-duplicate on it. `test_…` in a test; `sub_<submission id>` when read with Get a Submission.
testverplicht	boolean	`true` for a test-send or a sample.
submissionverplicht	{ id: string, filename: string, reference: string \| null, uploaded_at: string, file_url: string \| null }
formverplicht	{ id: string, version: integer }
approvalverplicht	{ mode: "manual" \| "auto" \| "agent", by: string \| null, at: string }
dataverplicht	object	One key per Field of the Form, always present: `null` for no value. A List Field is an array of entries, each with every sub-Field key; `[]` for none.

Integration

Naam	Type	Beschrijving
idverplicht	string	Use it to list the Integration's Deliveries.
nameverplicht	string
kindverplicht	"webhook" \| "google_sheets" \| "excel"	Where it sends to. Vink may add kinds: treat a kind you don't know as opaque.
form_idsverplicht	string[]	The Forms it is attached to.
subscription_idverplicht	string \| null	The Subscription this Webhook is for; `null` for an Integration an Admin made.
needs_reconnectverplicht	boolean	Its connected account no longer lets Vink in, so its Deliveries fail until an Admin reconnects it in Vink. Always `false` for a Webhook.

Delivery

Naam	Type	Beschrijving
idverplicht	string	Use it to send the Delivery again.
delivery_idverplicht	string	The `delivery_id` of the envelope the receiver gets: the same on every attempt and retry.
submission_idverplicht	string
integration_idverplicht	string	Still set after the Integration was removed.
integration_nameverplicht	string	The Integration's name when the Delivery was made.
stateverplicht	"pending" \| "retrying" \| "delivered" \| "failed"	`pending`: about to be sent. `retrying`: an attempt failed and another follows at `next_attempt_at`. `delivered` and `failed` are final, until a failed one is sent again.
failure_reasonverplicht	string \| null	Why the last attempt failed, for people.
next_attempt_atverplicht	string \| null	Set while `retrying`.
can_retryverplicht	boolean	Whether Send a Delivery again takes it: it is `failed`, its Integration is still there and its Submission's data is not deleted.
created_atverplicht	string	When the Submission was approved.
attemptsverplicht	DeliveryAttempt[]	Oldest first.

DeliveryAttempt

Naam	Type	Beschrijving
atverplicht	string
statusverplicht	integer \| null	The receiver's HTTP status; `null` when it didn't answer.
errorverplicht	string \| null	Why there was no answer, such as a timeout.
bodyverplicht	string \| null	The first 500 characters of the receiver's answer; `null` once the Submission's data is deleted.

DeliveryList

Naam	Type	Beschrijving
dataverplicht	Delivery[]
next_cursorverplicht	string \| null	Pass it as `cursor` for the next page; `null` on the last page.

FormDescription

Naam	Type	Beschrijving
descriptionverplicht	string	What the document is and which data you need, at most 2000 characters.

CreatedFormProposal

Naam	Type	Beschrijving
idverplicht	string	The Form Proposal's id.
stateverplicht	"processing"	Always `processing` here.

FormProposal

Naam	Type	Beschrijving
idverplicht	string
stateverplicht	"processing" \| "ready" \| "failed"	`processing`: Vink reads the sample and proposes Fields. `ready`: `fields` holds them. `failed`: see `failure`; an Admin can retry in the app.
sourceverplicht	"sample" \| "description"
filenameverplicht	string	The sample's name, or a description's first words.
descriptionverplicht	string \| null	The description it was made from; `null` for a sample.
failureverplicht	string \| null	`unreadable`: the sample can't be read. `failed`: every attempt failed; a retry may work. `null` unless `state` is `failed`.
created_atverplicht	string
fieldsverplicht	array \| null	The proposed Fields once `ready`, else `null`. None is required; an Admin decides that when saving.

Usage

Naam	Type	Beschrijving
planverplicht	string \| null	The Plan (`starter`, `team`, `business`, `scale`, `custom`), or `null` without one. Vink may add Plans.
unlimitedverplicht	boolean	`true` when Vink never refuses for Credits.
credits_leftverplicht	integer \| null	Credits left: free Credits plus what is left of the Plan this period. `null` when `unlimited`.
credits_usedverplicht	integer	Credits used this period.
resets_atverplicht	string \| null	When the period ends and the Plan's Credits are full again; `null` without a Plan.