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`	POST	Initiates the creation of a new Document under the specified Document Definition. The process may involve providing initial data in the request body.
`/{id}`	PUT / PATCH	Updates an existing Document by its ID within the specified Document Definition. Requires a request body with the fields to update.
`/{id}`	DELETE	Deletes a specific Document by its ID within the specified Document Definition.

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] }
  }
}