Import Documents

See the Document Object reference for the structure of the document payload.

POST/api/2026-03/import/documents

public-api:write

Latest version

ACCESS_TOKEN=ey1234
curl -k -X POST "https://server.livingdocs.io/api/2026-03/import/documents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @- << EOF
  {
    "systemName": "identifier-for-your-system",
    "webhook": "https://my-domain.com/webhooks/document-import",
    "documents": []
  }
  EOF

Request Body

JSON Body

Sent as JSON in the request body.

Parameter	Type	Description
`systemName`*	`string`	Identifier for the system you are importing from, e.g. an archive
`webhook`	`uri`	Endpoint at the importing system that gets notified by POST when import job is done. Notification contains the id of the import job, the state and an overview.
`context`	`object`	An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes.
`documents`*	`array`	An array of documents to import. Each entry is an object with the following keys: id: a unique id (stored as externalId in Livingdocs) that identifies the document on your end, must be unique within your project. title: the title that the document should get in livingdocs checksum: string to identify changes, e.g. an updated_at timestamp contentType: the content type that the document should get in livingdocs publishControl: An object with `firstPublicationDate`: sets the first publication date `significantPublicationDate`: ((added in release-2023-07)) sets a date which can be used by deliveries to display to viewers `visiblePublicationDateOverride`: ((added in release-2024-01)) sets a date which can be used by deliveries to display to viewers `lastPublicationDate`: sets the most recent publication date The `autoPublish` flag must be set for 'publishControl' to have an effect. publicationDate: ({{< deprecated-in "release-2023-03" >}}) Please use `publishControl.lastPublicationDate`. Sets the most recent publication date. The `autoPublish` flag must be set for this to have an effect. content: (optional) An array of livingdocs components, must conform to your channel-config otherwise throws a validation error design: (optional) An object with `name` and `version`. If no design is set it takes the design of the Project Config with the latest version metadata: (optional) An object of metadata, must conform to your channel-config otherwise throws a validation error translations: (optional) An object of translations flags: (optional) define additional import logic: `autoPublish`: publishes imported documents immediately `unpublish`: unpublishes imported documents immediately `onlyOverwriteUntouched`: only update documents that have no manual changes in livingdocs `neverOverwrite`: never update documents through the import API

Description

The document import does both create and update documents. The import remembers the externalId / systemName pair and if an import matches an existing pair, it will update (Hint: consider how to rebuild the externalId when you want to update documents). The document import in Livingdocs is asynchronous. You post a batch of documents that you want to import and get back an id with which you can query later to get your result.

Use Cases

Initial Import from a legacy system

Responses

{
  "id": "25bzj8j"
}

GET/api/2026-03/import/documents/status

public-api:write

Latest version

ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/2026-03/import/documents/status" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Query Parameters

Query String

Passed as URL query string. Comma-separated values for arrays (e.g. ?contentTypes=regular,author).

Parameter	Type	Description
`id`*	`string`	The id that Livingdocs provided you for your prior call to `/api/:apiVersion/import/documents`

Description

This endpoint allows you to check the status of a previously initiated document import. The result will indicate whether the import has finished and its state.

Responses

{
  "finished": true,
  "state": "success",
  "id": "25bzj8j",
  "logs": [
    {
      "state": "imported",
      "system_name": "external-system-name",
      "external_id": "8Sv9Nu0d",
      "document_id": 1,
      "checksum": "123abc",
      "project_id": 3,
      "channel_id": 2,
      "revision_id": 4602,
      "version": 1,
      "id": 1
    },
    {
      "state": "published",
      "created_at": "2024-12-03T23:38:29.789Z",
      "updated_at": "2024-12-03T23:38:29.789Z",
      "system_name": "external-system-name",
      "external_id": "9av23oaf",
      "document_id": 1148,
      "checksum": "10",
      "project_id": 3,
      "channel_id": 2,
      "revision_id": 4603,
      "version": 1
      "id": 1,
    },
    {
      "state": "failed",
      "reason": "Invalid metadata",
      "external_id": "external-unique-id-345",
      "title": "my second document"
    }
  ]
}

{
  "finished": false,
  "state": "started",
  "id": "243kdc",
  "startedAt": "2020-01-01 13:45:12"
}

{
  "finished": true,
  "state": "failed",
  "id": "098shjhv9"
}

{
  "finished": false,
  "state": "lost",
  "id": "no import job found for id \"098shjhv9\""
}