---
title: "Update a public link"
method: PUT
path: "/links/{linkId}"
tags: ["links"]
---

# Update a public link

`PUT /links/{linkId}`

## Request

- Base URL: `https://docs-api.formify.eu/v1`
- URL: `https://docs-api.formify.eu/v1/links/{linkId}`
- 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`)

Replaces the link's configuration. The document is rebuilt from scratch with the slots you send, so
send the whole configuration — anything omitted is lost, except `fileId`, which keeps the current
document when omitted.

### The public URL survives
`linkUrl` is unchanged by an edit. Anyone already holding the link keeps a working link.

### Billing
An edit is **not** billed again — the existing link instance is carried over to the rebuilt link.

### When editing is refused
Two states answer `409`:

- **Disabled.** Disabling is permanent, so there is nothing left to edit. Duplicate the link instead —
  `POST /links/{linkId}/duplicate` gives you the same configuration as a new, billed link.
- **Still processing.** A link created or edited with the AI assistant enabled reports
  `status: "processing"` while the assistant reads the document, and cannot be edited until that
  finishes. Poll `GET /links/{linkId}` until it reports `active`, then edit.

### Access
Owner only. A colleague can read and disable a shared link but not edit it.

## Path parameters

- `linkId` string, uuid, required

## Request body

- UpdatePublicLinkRequest: Replaces the link's configuration. Anything you leave out is **not** preserved — send the full configuration, the same way you would to `POST /links`. `fileId` is the one exception: omit it to keep the link's current document.
  - `fileId` string, uuid: File ID from `POST /files`. Omit to keep the link's current document.
  - `name` string: Name of the link. Omit to keep the current name.
  - `sharingSetting` 'private' | 'shared': See `CreatePublicLinkRequest.sharingSetting`.
  - `language` 'en' | 'sv' | 'es': Language of the signing experience
  - `signeeDetails` PublicLinkSignatureField[], required: Replaces the link's signature slots entirely.
    - `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 `200`

Public link updated 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
- `401`: Unauthorized - Missing or invalid access token.
- `403`: Forbidden - not the owner, or a required capability is missing.
- `404`: Public link not found
- `409`: Conflict - the link is disabled, still being processed by the AI assistant, or its source document is no longer available, so it cannot be rebuilt.
- `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)