---
title: "Create a public link"
method: POST
path: "/links"
tags: ["links"]
---

# Create a public link

`POST /links`

## Request

- Base URL: `https://docs-api.formify.eu/v1`
- URL: `https://docs-api.formify.eu/v1/links`
- Auth: OAuth 2 (authorization code, authorization URL `https://docs-api.formify.eu/v1/oauth/authorize`, token URL `https://docs-api.formify.eu/v1/oauth/token`, scopes: `write`)

Creates a reusable public signing link from a file you have already uploaded with `POST /files`.
The link is live as soon as this returns — share `linkUrl` yourself, Formify sends nothing.

### Requirements
- `fileId` is **required**.
- `signeeDetails` must contain at least one slot.
- Every slot with `signaturePlacement: existing` (the default) must include `signatureBox`. There is no
  template to inherit coordinates from.

### Billing
Requires the `publicLinksCreate` capability. On the credits pricing model this allocates a billed link
instance and charges it pro rata for the rest of the current period, then renews it each period while
the link stays active. If the wallet cannot cover the charge the request is refused with `402` and no
link is created. A suspended account is refused with `403`.

Signatures collected through the link are charged separately, as they happen.

### AI assistant
With `aiAssistant.enabled` set to `true` the link is created with `status: "processing"` and
`linkUrl` is `null` until the assistant has finished reading the document. Poll `GET /links/{linkId}`
until `status` is `active`.

## Request body

- CreatePublicLinkRequest
  - `fileId` string, uuid, required: File ID from `POST /files`
  - `name` string: Name of the link. Shown in Formify, not to signers.
  - `sharingSetting` 'private' | 'shared': `private` (default) — only you can see and manage the link. `shared` — everyone on the account can. Requires the `accessLevels` capability. This controls who may administer the link inside Formify. It has no effect on who may *sign* it: a public link is public by definition.
  - `language` 'en' | 'sv' | 'es': Language of the signing experience shown to whoever opens the link
  - `signeeDetails` PublicLinkSignatureField[], required: The signature slots on the link. At least one is required.
    - `fullName` string: A **label** pre-filled on the signature line, not an identity. A public link has no known signer, so this is normally a role — `"Buyer"`, `"Witness"` — and whoever signs can overwrite it. Leave it empty and the signer is asked to type their own name instead.
    - `signatureType` 'digital_ink' | 'bankid_identification' | 'digital_ink_id_scan' | 'face_liveness': Type of signature / identity verification used by whoever signs this slot. Same values and the same capability requirements as on a document — see `SignatureField.signatureType`.
    - `signaturePlacement` 'existing' | 'new_page': Place the signature on an existing page (`existing`, default) or on a dedicated A4 page appended to the document (`new_page`). `digital_ink_id_scan` does not support `new_page`.
    - `requireNameClarification` boolean: Ask the signer to type their name next to the signature. Defaults to `true`, which is normally what you want on a public link, since the slot has no identity of its own.
    - `hidePersonalNumber` boolean: Leave the signer's personal number out of the rendered signature. Only meaningful for signature types that collect one.
    - `useInitials` boolean: Render the signature as initials rather than a full signature.
    - `paymentLink` object, nullable: Collect a payment before this slot can be signed. `null` when the slot requires no payment. The payment link must allow multiple use — one public link is signed by many different people, so a single-use payment link would stop working after the first of them. Payment links themselves are set up in the Formify client, not through this API. This property is returned as well as accepted so that a read-modify-write round trip does not drop a payment requirement configured there. Requires the `signAndPay` capability.
      - `id` string, uuid: Identifier of an existing payment link on the account.
      - `requireEmailVerification` boolean: Require the payer to verify their email address before paying.
    - `signatureBox` object: Placement of the signature field. **Required** when `signaturePlacement` is `existing`. Base size before scaling: - Width: 219 points - Height: 58 points
      - `page` integer: Page number where the signature box should be placed. The first page has index 0.
      - `x` integer: X-coordinate for the signature box placement (minimum value 0)
      - `y` integer: Y-coordinate for the signature box placement (minimum value 0)
      - `scale` number, float: Scales the entire signature field. Applies only when `signaturePlacement` is `existing`.
    - `idScanBox` object: Placement of the scanned ID placeholder, required when `signatureType` is `digital_ink_id_scan` and unused otherwise. Base size before scaling: - Width: 218 points - Height: 138 points
      - `page` integer: Page number where the ID scan placeholder should be placed. The first page has index 0.
      - `x` integer: X-coordinate for the ID scan placeholder placement (minimum value 0)
      - `y` integer: Y-coordinate for the ID scan placeholder placement (minimum value 0)
      - `scale` number, float: Scales the entire ID scan placeholder.
  - `disablePrinting` boolean: Prevent signers from printing the document.
  - `aiAssistant` AiAssistant: Configuration for the optional AI Assistant shown to signees while reviewing and signing a document. **Usage:** - Set `enabled` to `true` to activate the assistant for the document. - Set `textToSpeech` to `true` if the assistant should be able to read its responses aloud. - Use `language` to control the assistant language. **Defaults:** - `enabled`: `false` - `textToSpeech`: `false` - `language`: `en` **Processing:** When the AI Assistant is enabled, the document will be created with `status: "processing"` and `documentUrl` will be `null`. The document will be finalized asynchronously, and invitations to signees will be sent once processing is complete. > **Availability:** Requires the `aiAssistant` capability. Check `GET /account/capabilities`.
    - `enabled` boolean: Enables the AI Assistant for the document.
    - `textToSpeech` boolean: Enables text-to-speech so the assistant can read its responses aloud.
    - `language` 'ar' | 'bg' | 'zh' | 'hr' | 'cs' | 'da' | 'nl' | 'en' | 'fil' | 'fi' | 'fr' | 'de' | 'el' | 'hi' | 'id' | 'it' | 'ja' | 'ko' | 'ms' | 'pl' | 'pt' | 'ro' | 'ru' | 'es' | 'sv' | 'ta' | 'tr' | 'uk': Language used by the AI Assistant. Supports 28 languages.
  - `errorLanguage` 'en' | 'sv' | 'es': Language for error messages

## Response `201`

Public link created successfully

- PublicLinkListDetail
  - `linkId` string, uuid: Unique identifier of the public link
  - `name` string: Name of the link
  - `createdAt` string, date-time: When the link was created
  - `updatedAt` string, date-time, nullable: When the link was last edited
  - `userId` string, uuid: User ID of the link owner
  - `sharingSetting` 'shared' | 'private': Who on the account may administer the link
  - `status` 'active' | 'disabled' | 'processing': - `active`: the link is live and can be opened and signed. - `disabled`: the link has been switched off and no longer accepts new signers. Documents already produced by it are unaffected. There is no way to switch it back on. - `processing`: the AI assistant is still reading the document. `linkUrl` is `null` and the link cannot be edited until this finishes. Note this is a different set of values from a document's `status` — a link is a source of documents rather than a signature request, so it has no signing progress of its own.
  - `linkUrl` string, nullable: The link to share. `null` while `status` is `processing`, because the document is not servable yet. Uses the account's custom domain when one is configured. Formify never sends this to anyone — distributing it is up to you.

## Other responses

- `400`: Invalid request parameters (missing field, wrong format, coordinates outside the document, etc.)
- `401`: Unauthorized - Missing or invalid access token.
- `402`: Payment required - not enough credits to allocate a new link instance. No link is created.
- `403`: Forbidden - missing `publicLinksCreate` capability, or the Formify subscription is suspended.
- `404`: File not found.
- `500`: Internal server error.

---

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