# AnnotationsApi.importXFDF()

```ts
importXFDF(xml: string, options?: XFDFImportOptions): Promise<XFDFImportResult>
```

Applies an XFDF file: its annotations are written as `create()`, `reply()` and `setStatus()` write them, with the file's names, authors, subjects and dates (a `freetext` as the Text Box tool writes it, from its `<defaultappearance>`), and its `<fields>` go through `doc.forms.setValues()`.

`options.mode`: `'merge'` (default) — an entry whose `name` the document already has replaces that annotation in place, keeping the replies in the document the file does not bring back (unless the file moves it to another page, where a thread cannot follow: the old one goes with its thread), and every other entry is added; `'replace'` — every annotation the file could describe (text marks, notes, shapes, drawings, polygons, free text, replies, statuses) is removed first, so the document ends up with the file's alone; stamps, links and form fields stay either way.

`skipped` reasons: `unsupported` (a stamp, caret, attachment, sound or redaction, a state that is not a review status, an unknown element), `no_page`, `invalid` (missing geometry or a refused value, or a name that belongs to a form field, link or pop-up), `no_parent` (a reply to nothing). `flags` are written as the file states them; a member of a group (`replyType="group"`) becomes an annotation of its own; an empty attribute is read as none. A name the API cannot write (an `obj:…` id, one too long) gets a fresh UUID; `dashes`, `icon` and a pop-up's own place are read but not written. The license is checked for both halves before either is written, and one `annotations` change is announced at the end. Needs `annotations` when the file has annotations, `forms` when it has fields.

On a certified document the annotations go in only where its certification allows them (`'annotations'`): at `'forms'` a file with annotations is refused with `INVALID_STATE` unless `options.invalidateSignatures` (pass `annotations: false` to take its field values alone), and at `'none'` the field values are rejected as `read_only`.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `xml` | `string` | A well-formed XFDF document. |
| `options?` | `XFDFImportOptions` | `mode` (`'merge'`, the default, or `'replace'`), `annotations` and `fields` (default `true`; switch each half off) and `invalidateSignatures`. |

Returns `Promise<XFDFImportResult>`: `imported` and `replaced` ids, `fields` (what `setValues` reported, or `null`), and `skipped` — every entry not applied, with its `element`, `page`, `name`, a `reason` (`unsupported`, `no_page`, `invalid`, `no_parent`) and an English `message`.

Throws:

- `INVALID_ARGUMENT` — text that is not a well-formed XFDF document, or a `mode` that is neither.
- `FEATURE_NOT_LICENSED` — the license lacks `annotations` (file with annotations) or `forms` (file with fields).
- `INVALID_STATE` — a certified document whose certification forbids the file's annotations, unless `options.invalidateSignatures`; or a progressive document still downloading.
- `DOCUMENT_CLOSED` — the document has been closed.

```ts
const { imported, replaced, skipped, fields } = await doc.annotations.importXFDF(
  await (await fetch('/reviews/' + id)).text(),
);
if (skipped.length > 0) console.warn('Not applied:', skipped);
```

Part of [AnnotationsApi](https://kernstra.com/docs/web-sdk/api/doc-annotations) in the Kernstra Web SDK 1.0.0 API reference.

Web page: https://kernstra.com/docs/web-sdk/api/doc-annotations/importxfdf