Getting Started with the API

Introduction

Welcome to the mDocs+ API documentation! This section will guide you through the initial steps needed to start using our API.

Prerequisites

Before you begin, make sure you have the following:

An active account: If you don't have one yet, make sure an account has been created for you.
An API key: You can find your API key in your profile, under the API tab.

HTTP Headers

Enhance your interaction with the API by using special features available on certain endpoints. You can access these features by adding parameters to the request header.

Headers

Field	Type	Description	Default value	Required
Authorization	Bearer Token	Authentication token		✔️
expand	string	Expanded fields
fields	string	Fields returned by the request
href	boolean	Returns the URL of an individual document	false
dateFormat	string	Formats date and time fields	php:d.m.Y H:i:s
dateFields	string	Formats only the specified fields
ignoreMissingReference	boolean	(true\|false) Used with reference-based field setting	false
ignoreDuplicateReference	boolean	(true\|false) Used with reference-based field setting	true
fillPlaceholders	boolean	When uploading .docx files, it automatically attempts to fill in the 'placeholder' fields.	false
removeUnfiledPlaceholders	boolean	When uploading .docx files, it hides all 'placeholder' fields that were not filled in automatically.	false

Example

{
  "Authorization": "xfWuluzj...",
  "expand": "documentType.*,createdBy.name",
  "fields": "id,subject",
  "href": "true",
  "dateFormat": "php:d/m/Y",
  "dateFields": "created_at,updated_at",
  "ignoreMissingReference": "true",
  "ignoreDuplicateReference": "false",
  "fillPlaceholders": "false",
  "removeUnfiledPlaceholders": "false"
}

Authorization

The "Authorization" header is a key component in securing access to server resources, as it serves as the means of authenticating users or applications sending requests. It must be included in every API request, since it ensures that access is granted only to authorized parties.

You can find your API_KEY in your profile, under the API tab.

Fields

The "Fields" header enables selective retrieval of data — when you list the fields you want in the header, the server includes only those fields in the response. This lets you receive only the information you actually need, which optimizes data transfer and simplifies handling of the response.

By specifying id, created_at and created_by in the "fields" parameter, the request is adjusted so that the response contains only this essential information.

{
  "id": 5,
  "created_at": "14.11.2025 10:11:31",
  "created_by": 13
}

Expand

The "Expand" header is a feature that improves data retrieval, as it allows detailed information from related fields (lookup tables) to be included.

For example, if a record stores a reference such as created_by, this usually points to a user (their id). The reference alone doesn't provide enough context. Using this header, you can specify additional attributes, such as createdBy.id, createdBy.username, and so enrich the response with more meaningful data.

This feature makes it possible to include the username directly in the response, giving a clearer picture of where the document came from.

{
  "id": 5,
  "created_at": "14.11.2025 10:11:31"
  "createdBy": {
    "id": 13,
    "username": "superadmin"
  }
}

Href

The "Href" header is a feature that adds a URL to the retrieved document in the response.

DateFormat

The "DateFormat" header is a feature that lets you format date fields. By specifying the desired format in the request header, you can make sure date and time data is returned in the structure that suits you best.

Formatting

Below are the format specifications you can use with the DateFormat header, including descriptions and examples:

Default value

Format pattern: php:d.m.Y H:i:s
Description: The default value used when dateFormat is not set.
Example: 15.02.2024 12:11:31

ISO 8601 Date and Time

Format pattern: php:Y-m-d\TH:i:s\Z
Description: Formats the date and time according to the ISO 8601 standard, which is commonly used for internationalization.
Example: 2024-02-15T12:11:31Z

Short Date

Format pattern: php:d/m/Y
Description: Gives a compact date display without the time, ideal for simple date displays.
Example: 15/02/2024

Long Date with Textual Month

Format pattern: php:d F Y
Description: Displays the date with the full month name, giving a more readable format for content-focused applications.
Example: 15 February 2024

Full DateTime with Day Name

Format pattern: php:l, d F Y H:i:s
Description: Includes the full date and time together with the day of the week, providing comprehensive time information.
Example: Friday, 15 February 2024 12:11:31

DateFields

The "dateFields" header is a feature that allows only the specified fields to be formatted, using the format set in the "dateFormat" header.

Query Parameters

Some GET requests allow you to filter data by adding query parameters based on field names.

For example, using ?country=slovenia as a query parameter will return all users from Slovenia. You can also increase the precision of the query by adding more parameters, but to add several filters correctly you must use the & symbol instead of repeating ?.

For example, ?country=slovenia&full_name=janez will return users from "Slovenia" whose name is "janez".

Besides filtering requests by field names, you can also adjust pagination: Pagination is set by default to return the first 20 results. Use the page parameter to specify which page the API should return, while the per-page parameter determines how many results are shown per page.

Example: page=2&per-page=5 will return 5 results from the second page.

Reference Fields

Many records can have a field that stores a reference to another record.

A field that represents a reference can usually be recognized by its name — in most cases the field name ends in _id, e.g. document_type_id or classification_code_id. The exceptions are the fields created_by and updated_by.

Because these fields only store a reference (id) to another record, you can use the Expand header when retrieving data. When creating or updating a record, you can use reference-based field setting.

Reference-Based Field Setting

Reference fields always store the identifiers of related records, so identifiers must always be used when working with related fields.

For example, say you want to set the following referenced record on the related field document_type_id:

// get document-type/

{
  "id": 2,
  "uuid": "6be1...V98",
  "name": "Certifikat",
  "description": "Certifikat xyz"
},

If you know the ID of the referenced record you can of course set it directly, but you can also set it through a reference, using the following format:

"$ref.[polje]": "[mdocs_model_class];[polje_za_iskanje];[iskan_niz]"

You can obtain the [mdocs_model_class] value with the info call, described here.

// create document/

{
  "document_type_id": 2
  // ali
  "$ref.document_type_id": "mikrografija.mdocs.document.models.DocumentType;name;certifikat"
  // ali
  "$ref.document_type_id": "mikrografija\\mdocs\\document\\models\\DocumentType;name;certifikat"
},

In the example above, all three approaches achieve the same result. The first sets the field directly, while the other two go through a reference.

In the second approach, we tell the API that we want to create a document record where the document_type_id field should store the document-type whose name field equals 'certifikat'.

Reference Headers

When setting a field by reference, you can use two additional headers:

ignoreMissingReference

Defaults to false

If a document-type with name = 'certifikat' doesn't exist, the API call will not succeed. Using the ignoreMissingReference header, you can ignore this error — the field will be set to null.

ignoreDuplicateReference

Defaults to true

If there are two records with the value name = 'certifikat', the record with the higher identification number is used (id = 3 in the example below).

Using the ignoreDuplicateReference = false header, the API call will not succeed if there are duplicate records.

fillPlaceholders

Defaults to false

When uploading .docx files, it automatically attempts to fill in the 'placeholder' fields.

removeUnfiledPlaceholders

Defaults to false

When uploading .docx files, it hides all 'placeholder' fields that were not filled in automatically.

// get document-type/

{
  "id": 2,
  "uuid": "6be1...V98",
  "name": "Certifikat",
  "description": "Certifikat xyz"
},
{
  "id": 3,
  "uuid": "asg4...G3D",
  "name": "Certifikat",
  "description": "Certifikat 123"
},

Introduction​

Prerequisites​

HTTP Headers​

Headers

Authorization​

Fields​

Expand​

Href​

DateFormat​

Formatting​

Default value​

ISO 8601 Date and Time​

Short Date​

Long Date with Textual Month​

Full DateTime with Day Name​

DateFields​

Query Parameters​

Reference Fields​

Reference-Based Field Setting​

Reference Headers​

ignoreMissingReference​

ignoreDuplicateReference​

fillPlaceholders​

removeUnfiledPlaceholders​

Introduction

Prerequisites

HTTP Headers

Authorization

Fields

Expand

Href

DateFormat

Formatting

Default value

ISO 8601 Date and Time

Short Date

Long Date with Textual Month

Full DateTime with Day Name

DateFields

Query Parameters

Reference Fields

Reference-Based Field Setting

Reference Headers

ignoreMissingReference

ignoreDuplicateReference

fillPlaceholders

removeUnfiledPlaceholders