Documents API

This works with the document-definitions so read the introduction there first and get some basic knowledge of the core features. The documents are used for saving data per document definitions. A document definition can hold a lot of documents and using this API and the features it support we can select the one we need.

For v1 documentation about the documents calls can be found here

Documents Endpoints

These endpoints allow interaction with the individual Documents created based on a Document Definition. All Document endpoints require specifying the parent Document Definition.

Core Resource Path

The core path for interacting with Documents is rooted under a specific Document Definition:

api/v2/document-definitions/{ddId}/documents

{ddId}: Replace with the ID or name of the document definition itself. Can be used with getting the document definition of where the document action is called from using serverDocument._documentDefinitionId

Endpoints

The following endpoints are available for Documents, relative to the Core Resource Path:

URL	HTTP Method	Description
`Core path`	GET	Retrieves a list of Documents belonging to the specified Document Definition. Supports filtering, sorting, and pagination via query parameters.
`/{id}`	GET	Retrieves the details of a specific Document by its ID (internal or external) within the specified Document Definition.
`/new`	GET	Returns a new, empty Document with the default values of the specified Document Definition. Nothing is saved.
`Core path`	POST	Creates a new Document under the specified Document Definition. The request body is the Document. It must contain `_documentDefinitionId`, `_environmentId` and `status`. To set an external ID, include `externalId` as a field in the body.
`/{id}`	PUT	Updates an existing Document by its ID (internal or external) within the specified Document Definition. Requires a request body with the fields to update.
`Core path`	DELETE	Deletes one or more Documents within the specified Document Definition. The IDs are passed in the request body, either as `ids` (internal `_id` values) or as `externalIds`. There is no `/{id}` variant. See Example 4.

External IDs are not unique

externalId is not enforced to be unique by the database. If multiple Documents share the same externalId, GET and PUT on /{id} resolve to whichever of them the database returns first, and DELETE with externalIds removes all matching Documents. Keep externalId values unique yourself if you use them to identify a single Document.

Examples

This section will provide examples to give a start to your own scripts and understanding of the curl commands. There will be used of some place holders like [Main API Domain] and the YOUR_ACCESS_TOKEN.

To use the documents and calling them we need to make sure you have access from the account in relation to the environment. This means you always need to add:

-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "environment-id: Env_id"

or

  'Authorization': `Bearer ${authToken.accessToken}`,
  'environment-id': serverDocument._environmentId

Example 1: Listing Documents for a Document Definition

This example shows how to retrieve a list of all documents that belong to a specific Document Definition using the definition's ID.

curl -X GET "[Main API Domain]/api/v2/document-definitions/dd_customers/documents" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "environment-id: Env_id"

or

const loginEndpointValidate = `api/v2/document-definitions/${serverDocument._documentDefinitionId}/documents`;
const loginMethodGet = 'GET';
const headers = {
  'Accept': 'application/json',
  'Authorization': `Bearer ${authToken.accessToken}`,
  'environment-id': serverDocument._environmentId
};
const DocumentsList = REST.call(loginEndpointValidate, loginMethodGet, headers, {});
console.log(DocumentsList);

Expected Response (200 OK):

{
  status: 'ok',
  data: [
    {
      _id: '681216b52eb8530341ec07e9',
      _lastModifiedByUserId: '1YNEXKYkPnqk52Fzf',
      _lastModifiedOn: '2025-04-30T12:25:28.275Z',
      _createdOn: '2025-04-30T12:25:28.275Z',
      _createdByUserId: '1YNEXKYkPnqk52Fzf',
      status: 'ready',
      _hash: '',
      _documentDefinitionId: 'CghGFDo90qxqKaJI25owl',
      _environmentId: 'maxedy_pizza',
      accessGroups: [Array],
      ingredients: [],
      asd: [],
      name: 'New Document Name',
      inStock: false,
      externalId: 'someExternalId',
      mainIngredient: 'ingredient15',
      size: 'medium',
      _permissions: [Object]
    },
    {
      _id: '681216bc2eb8530341ec0810',
      _lastModifiedByUserId: '1YNEXKYkPnqk52Fzf',
      _lastModifiedOn: '2025-04-30T12:25:33.874Z',
      _createdOn: '2025-04-30T12:25:33.874Z',
      _createdByUserId: '1YNEXKYkPnqk52Fzf',
      status: 'ready',
      _hash: '',
      _documentDefinitionId: 'CghGFDo90qxqKaJI25owl',
      _environmentId: 'maxedy_pizza',
      accessGroups: [Array],
      ingredients: [],
      asd: [],
      name: 'New Document Name',
      inStock: true,
      externalId: 'someExternalId',
      mainIngredient: 'ingredient15',
      size: 'medium',
      _permissions: [Object]
    },
        // etc
  ]
}

If an error it will return something like this:

{
    "status":"error",
    "error":"document_definition_not_found_for_id_or_name",
    "description":"The document definition could not be found for \"id\" or \"name\": 611bca4873b487007584ace0 in maxedy_pizza environment","userDescription":"The document definition could not be found for \"id\" or \"name\": 611bca4873b487007584ace0 in maxedy_pizza environment",
    "message":"The document definition could not be found for \"id\" or \"name\": 611bca4873b487007584ace0 in maxedy_pizza environment"
}

Example 2: Getting a specific Document

This example demonstrates how to retrieve the full details of a single document using its ID within the context of its Document Definition.

curl -X GET "[Main API Domain]/api/v2/document-definitions/${serverDocument._documentDefinitionId}/documents/681216bc2eb8530341ec0810" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "environment-id: Env_id"

The expected result will look something like this:

{
    _id: '681216bc2eb8530341ec0810',
    _lastModifiedByUserId: '1YNEXKYkPnqk52Fzf',
    _lastModifiedOn: '2025-04-30T12:25:33.874Z',
    _createdOn: '2025-04-30T12:25:33.874Z',
    _createdByUserId: '1YNEXKYkPnqk52Fzf',
    status: 'ready',
    _hash: '',
    _documentDefinitionId: 'CghGFDo90qxqKaJI25owl',
    _environmentId: 'maxedy_pizza',
    accessGroups: [Array],
    ingredients: [],
    asd: [],
    name: 'New Document Name',
    inStock: true,
    externalId: 'someExternalId',
    mainIngredient: 'ingredient15',
    size: 'medium',
    _permissions: [Object]
},

Example 3: Copying a Document Definition

This example shows how to create a new Document Definition by copying an existing one using its source ID.

curl -X POST "[Main API Domain]/api/v2/document-definitions?sourceId=dd_customers" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
-H "environment-id: Env_id"
-d {
    clientDocument: {
      id: id
    } \
    actionInfo: {
      id: "SomeId"
    } \
    actionType:Type \
    ddId: documentDefinitionId \
    workflowId:Id \
    value: {
      id: value
    } \
    documentDefinitions: documentDefinitionId
  }

When a copy has succesfully be made it will look something like this:

{
  status: 'ok',
  data: {
        //Newly created document:
    _id: '670657efa1d5977feeaf52d4',
    _lastModifiedByUserId: '1YNEXKYkPnqk52Fzf',
    _lastModifiedOn: '2024-11-29T15:50:02.672Z',
    _createdOn: '2024-10-09T10:14:42.168Z',
    _createdByUserId: '1YNEXKYkPnqk52Fzf',
    _hash: 'x12moDTulqKtZ9vw7VyBK2K+/wJk8WwF5YPbKJdgJ84=',
    _documentDefinitionId: '66f297ee6e40b21d8c597c8c',
    _environmentId: '66f297ab6e40b21d8c597c50',
    accessGroups: [],
    name: 'Home',
    coordinates: {
      longitude: 5.7370552,
      latitude: 52.7145947,
      formattedAddress: 'De Fjord 49, 8303 HH Emmeloord, Netherlands'
    },
    city: 'Emmeloord',
    address: 'De Fjord 49',
    _permissions: { fullPermissions: true, userActionPermissions: [Array] }
  }
}

Example 4: Deleting Documents

Documents are deleted with a DELETE on the core path. The IDs go in the request body, as an array, even when you delete a single Document. Pass either ids (internal _id values) or externalIds; the two are mutually exclusive.

curl -X DELETE "[Main API Domain]/api/v2/document-definitions/dd_customers/documents" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "environment-id: Env_id" \
-d '{ "externalIds": ["someExternalId"] }'

To delete by internal ID instead, send ids in the body:

{ "ids": ["681216bc2eb8530341ec0810"] }

Deleting a Document also applies the When a Related Document is deleted setting of the reference fields that point to it. Depending on that setting, Documents that reference the deleted Document can be deleted too, or can prevent the deletion.

If none of the given IDs match a Document, the call fails with an error. If at least one matches, the call succeeds, even when other IDs do not match anything.