apiary.apib

FORMAT: 1A
HOST: https://tenant.acrolinx.cloud

# Acrolinx API

The REST-like Acrolinx API helps you: 
* Configure settings on your Acrolinx instance
* Retrieve information from your Acrolinx instance
* Build Acrolinx checking features into your content creation workflows.

## Acrolinx SDKs
Consider using [Acrolinx SDKs](https://github.com/acrolinx?q=sdk).

# Authentication and Authorization

To interact with Acrolinx, you must use authorized and authenticated. This requires an **access token**.

An **access token** is an encoded and cryptographically signed string. It has the following characteristics:

* It's associated with a user
* A user can have an infinite number of access tokens
* It has a certain lifetime (30 days default) that you can change
* It expires after the lifetime or when the password of the associated user is changed
* It provides authorization and authentication

Get an **access token**
To get an access token, sign in to Acrolinx.

**Note:** To learn more about creating API tokens, read [Create an API Token](https://support.acrolinx.com/hc/en-us/articles/10306041244818-Create-an-API-Token) in the Acrolinx documentation.

See also [Create an API token](#Create an API token (Self)).

Use an access token:

Every request you send to the Acrolinx API must contain a [header](#header-access-token) that includes an access token:

```
    X-Acrolinx-Auth: WERTZUIOP
```

## API token
An API token is an access token with special characteristics:

* It has a lifetime of 4 years
* It does **not expire when the password of the associated user is changed**
* A user can have only one API token associated with it at a time

To get an API token:
* Go to your Settings and create one.
* Use the **user API** programmatically. (See more under the section **User-generated API tokens**)

Besides that, the **API token** works like an **access token**.

# General headers

## Access token

All methods except "index" and "poll access token" require a valid access token in the `X-Acrolinx-Auth` header.
If the token is invalid, Acrolinx returns a `401` response. (see `401` response of "index").

Example:

```
    X-Acrolinx-Auth: 123579080a8d1fee12490a90dc3
```

## Base URL

To support reverse proxies, an integration may provide the `X-Acrolinx-Base-Url` header with each request. If the response body contains links to the API, 
Acrolinx will prefix them with the specified value. The value must be an absolute URL including scheme and host.
Malformed values will result in a `400` status code.

Example:

```
    X-Acrolinx-Base-Url: https://example.com/path/
```

## Integration locale

All methods accept a header `X-Acrolinx-Client-Locale` that the integration can use to identify its own locale (for example, UI language).
For the value of the header field, use a single language tag that complies with [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.txt). Acrolinx will try to return message strings
and other locale-specific parts of the response in the requested language.

Example:

```
    X-Acrolinx-Client-Locale: de-CH
```

Acrolinx tries to match to the nearest configured locale that it support, for example, `de`.
The "index" request returns a list of supported locales. Acrolinx falls back to the default `en` locale under the following conditions:

* No X-Acrolinx-Client-Locale header is sent
* There's no matching supported locale
* For the given response, there's no appropriate localization available

## Signature

If not otherwise documented, all methods require you to set a header `X-Acrolinx-Client`. The header needs to include a valid signature. 
If the header is missing or if the signature is invalid, the request returns an error.

The format of the signature is `Signature;Version`, where `Signature` is the signature as configured in the Acrolinx license and
`Version` is the version number of the integration.

Example:

```
    X-Acrolinx-Client: SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5; 1.0.1.45
```

# Response format

The API provides a consistent format for all responses. Each response has a `links` field and one of the three fields: `error`, `progress`, or `data`.

The `links` field contains further URLs that you can use as a next step in the workflow.
* `error` is set if the request didn't succeed. This includes an HTTP status code greater or equal to 4xx.
* `progress` means that the processing isn't done yet and the integration has to poll for the final result.
* `data` contains the actual result data. The processing finished successfully.

## Error responses

### General format

The API provides a consistent format for errors, which is based on [RFC7807](https://datatracker.ietf.org/doc/rfc7807/?include_text=1).
The format is JSON and the API guarantees to send the fields `type`, `title`, `detail`, and `status` with each error response.

Example:

```
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
  "error": {
    "type": "auth",
    "title": "Invalid authentication",
    "detail": "The provided token for authorization is not valid.",
    "status": 403
  }
  "links": {}
}
```

* `type` is a unique identifier for the type of error. Choose a workflow for error handling that works best for the type of integration (interactive or automated).
* `title` is a short description of the error. You can use this as the title of the error message that users see.
* `detail` is a longer description of the error. You can also include this in the error message.
* `status` is redundant to the HTTP status code. It may be helpful if a proxy changes the HTTP status code of the original API response.
* You might also see an optional `reference` field with an ID.

Depending on `type`, the response may include additional fields to provide more detailed information.

We may add additional fields in the future. An integration must not break because of unexpected fields.



### Error types

Type | Description| What to do
-----|------------|------------
`client` | Unspecific error caused by the integration's request. | Check logs and configuration or the integration code.
`server` | Unspecific Acrolinx error during processing of a request. | Check logs and configuration.
`clientSignatureMissing` | The `X-Acrolinx-Client` header was missing.  | [Contact Acrolinx](https://support.acrolinx.com/hc/en-us/requests/new) to learn how to get a valid signature.
`clientSignatureRejected` | The signature included in the `X-Acrolinx-Client` header was invalid. | [Contact Acrolinx](https://support.acrolinx.com/hc/en-us/requests/new) to get a valid signature.
`sso` | Returned for any single sign-on errors. | This is likely a configuration issue.
`auth` | Invalid authentication. | Use another access token.
`insufficientPrivileges` | Insufficient privileges. | Assign the required privileges to the user.
`interactiveSignInTimedOut` | The interactive sign-in process timed out. | Sign in again.
`checkCancelled` | The check was canceled. No result is available. | Probably points to an error in the integration.
`checkFailed` | The check failed. | Check logs and configuration.
`invalidBaseUrl` | The request contained an invalid base URL in the `X-Acrolinx-Base-URL` header. | Check the configuration of integration or proxies, which set the header.
`customFieldsIncorrect` | Custom field values are incorrect. | Provide valid values for all required custom fields before or when checking a document.
`validation` | Invalid request attributes. | Check the request for invalid values or missing parameters.
`guidanceProfileDoesntExist` | Style guide doesn't exist. | The style guide doesn't exist or isn't available for the user ID and language provided.
`noGuidanceProfileConfigured` | No style guide configured. | No style guide is configured for the user ID and language provided.
`contentTooLarge` | File too large. | Try checking less content.
`queueLimitExceeded` | Queue limit exceeded. | Wait at least as long as suggested in the retry-after header and try another check.
`conflict` | Concurrent write access. | Conflict with a concurrent write access. Try again with fresh data.
`licenseLimitExceeded` | License limit exceeded. | You exceeded a limit set by the terms of your license. The error description contains more details. For more information, check [the documentation](https://support.acrolinx.com/hc/en-us/articles/10306079192082-License-Types).
`entityToAssociateNotFound` | One or more associates to an entity could not be found. | Make sure that the given associates actually exist.

### Additional information on validation errors

Errors with type `validation` come with a list of constraint violation descriptions in an additional property `validationDetails`:

```
{
    "title": "Validation error",
    "constraint": "The 'languageId' is required.",
    "attributePath": "submit.arg1.languageId",
    "detail": "The 'languageId' is required but was 'null'.",
    "invalidValue": "DictionaryEntry{surface='TestSurface', scope=language, languageId='', guidanceProfileId='null', documentId='null'}",
    "possibleValues": ["en", "de"]
}

```
* `title`: "Validation error"
* `constraint`: A minimal description of the constraint that was violated.
* `attributePath`: A hint about the property or parameter that had an invalid value.
* `detail`: A more detailed description of the constraint violation.
* `invalidValue`: The value that was invalid. Can be a data structure.
* `possibleValues`: An optional list of valid values for the property.


The `validationDetails` provide developers with information to troubleshoot bad requests.
They are not intended for automated consumption.
There's no guarantee that values are always present or in a uniform format.



## Progress responses

A progress response always contains a `retryAfter` field, which tells the integration how many seconds to wait until the next poll request.
The response can optionally include both the `message` field with a human-readable text about the current status and a `percent`, which is
a number that shows the progress as a percent.
A progress response always has the `Retry-After` header set with the same value as the `retryAfter` field and an HTTP status 202.

Examples:

```
HTTP/1.1 202 Accepted
Content-Type: application/json
{
  "progress": {
    "message": "The request is queued on position 5.",
    "percent": 2,
    "retryAfter": 5
  }
  "links": {
    "cancel": "https://tenant.acrolinx.cloud/api/v1/checks/ID100"
  }
}
```

```
HTTP/1.1 202 Accepted
Content-Type: application/json
{
  "progress": {
    "retryAfter": 1
  }
  "links": {}
}
```

## Successful responses

The number of fields in successful response data depends on the request. For example, the response might contain additional fields if the 
original check request also asked for a Term Harvesting report.

Example:

```
HTTP/1.1 200 Ok
Content-Type: application/json
{
  "data": {
    "score": 99,
    "textualScore": "Good job!"
  }
  "links": {
    "submit": "https://tenant.acrolinx.cloud/api/v1/checks"
  }
}
```

# HTML fields

Responses may contain fields with HTML snippets that provide nice formatting in interactive integrations. These fields have a name that ends with "Html", for example, "guidanceHtml". Related fields with the same content may appear in plain text. If such a field exists, it will end with "Text" like in the example, "guidanceText".

All HTML fields only contain formatting tags that do not pose a security risk. A server-side allow list filters all tags.

# JSON - Escape special characters

Some JSON characters are special and require escaping. To escape a character, prefix the character with a backslash `\`.

Below are some common characters that need to be escaped in JSON:

|Character|Escape character|
|----------------|------------|
|Double quote|`\"`|
|Backslash|`\\`|
|Forward slash|`\/`|
|Backspace|`\b`|
|Form feed|`\f`|
|Newline|`\n`|
|Tab|`\t`|
|Unicode escape sequence for special characters|`\uXXXX`|

Example:
The value of the password is `backslash\quote"` in the JSON below. The special characters are escaped using a backslash.

```json
    {
        "username": "username",
        "fullName": "full Name",
        "password": "backslash\\quote\""
    }
```

# Group Index

## Index [GET /api/v1]

This endpoint returns general information about the current Acrolinx
version. Starting with version 2024.09, it also contains information
about the installed linguistic configuration (referred to as a
"guidance package"). Starting with version 2025.02, the response also
includes the expiration date and order number for the license that's currently installed.


**Note**: This is the only web service method that provides a 200 response if no access token was sent.

+ Request

    + Header

            X-Acrolinx-Auth: ""


+ Response 200 (application/json)

        {
          "data": {
            "platform": {
                "name": "Acrolinx Platform",
                "version": "2024.09.10156"
            },
            "server": {
                "name": "Core Server",
                "version": "2024.09.10846"
            },
            "guidancePackage": {
                "name": "Guidance Package for ACME",
                "version": "2024.09",
                "build": "7732",
                "date": "2024-09-13"
            },
            "locales": [ "en" ],
            "license": { // **Since Acrolinx 2025.02**
                "expiresAt": "2038-01-19T03:14:08Z",
                "orderId": 1729
            }
          },
          "links": {
            "signIn": "https://tenant.acrolinx.cloud/api/v1/auth/sign-ins"
          }
        }


+ Request

    + Header

            X-Acrolinx-Auth: 123579080a8d1fee12490a90dc3


+ Response 200 (application/json)

        {
          "data": {
            "platform": {
                "name": "Acrolinx Platform",
                "version": "2024.09.10156"
            },
            "server": {
                "name": "Core Server",
                "version": "2024.09.10846"
            },
            "guidancePackage": {
                "name": "Guidance Package for ACME",
                "version": "2024.09",
                "build": "7732",
                "date": "2024-09-13"
            },
            "locales": [ "en" ]
          },
          "links": {
            "signIn": "https://tenant.acrolinx.cloud/api/v1/auth/sign-ins",
            "submitCheck": "http://tennant.acrolinx.cloud/api/v1/checking/checks"
          }
        }


+ Response 401 (application/json)

        {  // if provided access token became invalid
          "error": {
            "type": "auth",
            "title": "Invalid access token",
            "detail": "The provided token for authorization is invalid.",
            "status": 401
          },
          "links": {}
        }

## Capabilities [GET /api/v1/capabilities]

Learn about capabilities of the individual APIs. This overview helps if you want to 
use more than one feature of the API.

+ Response 200 (application/json)
    + Attributes
        + data (object)
            + checking (object) - capabilities of the checking resource
            + document (object) - capabilities of the document resource
        + links (object)


# Group Authentication API

Authentication works with either a configured access token, with single sign-on (SSO), or interactively with the Acrolinx sign-in web page.
Embedded integrations use either the configured access token or SSO.
Interactive integrations with a human user use SSO or the interactive process.

## Request or validate an API token [POST /api/v1/auth/sign-ins]

The sign-in collection allows Acrolinx API integrations to request user authentication and to check
the validity and privileges of existing access tokens.

If Acrolinx is configured for single sign-on, then this endpoint will accept the configured credentials
to authenticate the request.

+ Request (application/json)

    + Header

            X-Acrolinx-Auth: 123579080a8d1fee12490a90dc3 (valid) OR (invalid/expired access token) OR (no access token)
            X-Acrolinx-Client-Locale: ja
            X-Acrolinx-Client: QWxlU2hNyb2bHVnLWlunhQyR29Rm9xpbvZ2lZXRz; 1.0.1.45;

+ Response 200 (application/json)
    No sign-in needed, the response body will contain valid access tokens.

    Acrolinx may decide that the request is already sufficiently authorized. In this case,
    no sign-in process is started. The response will contain the same information as after
    a successful sign-in. The following conditions may lead to this response:

    - The `X-Acrolinx-Auth` header contained a valid token.
    - Single sign-on is configured and valid credentials are provided.

    + Attributes (object)

+ Response 201 (application/json)
    If the `X-Acrolinx-Auth` header is absent a
    new sign-in process is started. The response body contains two links.
    One allows the user to complete the sign-in process.
    The other helps the integration to acquire the session data:

    - `interactive` a link to a web page that allows the user to authenticate and
          permit the integrations to access Acrolinx. If you provide a language in the
          `X-Acrolinx-Client-Locale` header, the link will point to a localized
          version of that web page if available and technically possible.

    - `poll` a link to a resource that will return an *access token* and information
          about the user after sign-in. (see [GET `api/v1/auth/sign-ins/{id}`](#authentication-api-poll-for-a-new-api-token-get))

    Note that the sign-in process will time out. The `interactiveLinkTimeout` field
    contains the length of time in seconds that the `interactive` link will stay valid. If the
    sign-in page was loaded before this time, Acrolinx will extend
    the timeout. To detect timeouts after opening the sign-in page, use the `poll` link.

    + Body

            {
              "data": {
                "state": "Started",
                "interactiveLinkTimeout": 900
              },
              "links": {
                  "interactive": "https://tenant.acrolinx.cloud/dashboard.html?login=19901-2-8412998412",
                  "poll": "https://tenant.acrolinx.cloud/api/v1/auth/sign-ins/185-0ijfgklejt2390tui"
              }
            }

    + Attributes
        + data
          + `state`:`Started` (string, required)
          + `interactiveLinkTimeout`: 900 (number, required)
        + links
            + `interactive`: `https://tenant.acrolinx.cloud/dashboard.html?login=19901-2-8412998412` (string, required)
            + `poll`: `https://tenant.acrolinx.cloud/api/v1/auth/sign-ins/185-0ijfgklejt2390tui` (string, required)

+ Response 401 (application/json)
    If invalid SSO credentials are supplied, the request is rejected. This occurs when an SSO username
    is present but the SSO password is wrong, missing, or the user couldn't be created.

    + Header

            WWW-Authenticate: ACROLINX_TOKEN, ACROLINX_SIGN_IN (, ACROLINX_SSO)

    + Attributes (object)

+ Response 503
    Acrolinx is unable to start a sign-in process at this time.

    + Header

            Retry-After: 30

    + Attributes (object)

## Poll for a new API token [GET /api/v1/auth/sign-ins/{id}]

Use polling so your integration waits for a user to authenticate and authorize before the integration can use the
Acrolinx API. Once the user has completed the sign-in process, the response will return a new access token.

When polling returns a final result, the polling endpoint will disappear and return a `NOT FOUND` status.

+ Parameters
    + id: `99576707-ed8c-44b6-82b8-c3ced8f349d1` (string, required) - poll-id for the authorization request

+ Request

    + Header

            X-Acrolinx-Client: QWxlU2hNyb2bHVnLWlunhQyR29Rm9xpbvZ2lZXRz; 1.0.1.45

+ Response 200 (application/json)
   A user completed the sign-in process and Acrolinx created a new access token.

   Note that this resource will disappear after this response.

   + Attributes (object)

+ Response 202 (application/json)
   The user hasn't authorized the sign-in yet. Request the same URI again to continue polling.
   Note that integrations should pace themselves by respecting the `Retry-After` header.

    + Header

            Retry-After: 2

    + Attributes
        + progress
           + `retryAfter`: 2 (number, required)

+ Response 404 (application/json)
    Acrolinx has no knowledge of the polling token. If you used a valid poll URI, the cause of this response is
    a timeout, or another poll request may have consumed the credentials.

    The returned type is `interactive_sign_in_timed_out`, which distinguishes this response from a normal 404 caused by a wrong URL.

    + Attributes
       + error
         + `type`: `interactive_sign_in_timed_out` (string, required)
         + `status`: 404 (number, required)
         + title: `The interactive sign-in process timed out` (string, required)
         + detail: `The interactive sign-in process timed out. Please start a sign-in.` (string, required)


# Group Checking API

The API for checking documents.

## List checking capabilities [GET /api/v1/checking/capabilities]

Use the checking capabilities to fetch a list of available style guides. If sublanguages are activated, they're included in the list of style guides.

For each style guide, Acrolinx provides information about the language, activated goals, and term sets. The integration may use this information
for filtering, but users can only select one style guide for checking. You cannot deselect individual goals within a style guide.

For each style guide, the goals contain an additional string field called `scoring`, which can have one of the following values:
* `required` (this goal counts towards the score and writers should prioritize issues found in this goal when creating content). 
* `recommended` (this goal is a recommendation only and does not count towards the overall document score).

**Note:** Before you get started with the Checking API, review the [authentication and authorization](https://acrolinxapi.docs.apiary.io/#introduction/authentication-and-authorization) requirements. 

+ Request

    + Headers

            X-Acrolinx-Auth: your_access_token
            X-Acrolinx-Client: your_client_signature

+ Response 200 (application/json)

        {
          "data": {
            "guidanceProfiles": [
                {
                    "id": "aud-1",
                    "displayName": "Tom the Technical Type",
                    "language": {
                        "id": "en-gb",
                        "displayName": "English (Great Britain)"
                    },
                    "goals": [{
                        "id": "CORRECTNESS",
                        "displayName": "Correctness",
                        "color": "#00bfa5",
                        "scoring": "required"
                    },
                    {
                        "id": "CLARITY",
                        "displayName": "Clarity",
                        "color": "#ec407a",
                        "scoring": "recommended"
                    },
                    {
                        "id": "WORDS_AND_PHRASES",
                        "displayName": "Words and Phrases",
                        "color": "#ea80fc",
                        "scoring": "required"
                    }],
                    "termSets": [{
                        "displayName": "Switches"
                    },
                    {
                        "displayName": "Acrolinx"
                    }]
                },
                {
                    "id": "aud-2",
                    "displayName": "Randolf Redakteur",
                    "language": {
                        "id": "de",
                        "displayName": "German"
                    },
                    "goals": [{
                        "id": "CORRECTNESS",
                        "displayName": "Correctness",
                        "color": "#00bfa5",
                        "scoring": "required"
                    }],
                    "termSets": []
                }
            ],
            "contentFormats": [
                {
                    "id": "auto",
                    "displayName": "Automatic Detection"
                },
                {
                    "id": "text",
                    "displayName": "Plain Text"
                },
                {
                    "id": "markdown",
                    "displayName": "Markdown"
                },
                {
                    "id": "xml",
                    "displayName": "XML"
                },
                {
                    "id": "word_xml",
                    "displayName": "XML (MS Word 2003)"
                }
            ],
            "contentEncodings": [ "none", "zip,base64", "base64" ],
            "referencePattern": "\\.(xml|xhtm|xhtml)$|\\.(md|markdown|mdown|mkdn|mkd)$|\\.(docx|docm|pptx|pptm|xlsx|xlsm)$|\\.txt$",
            "checkTypes": [ "batch", "interactive", "baseline", "automated" ],
            "reportTypes": ["extractedText", "termharvesting", "scorecard"]
          }
        }

##  Submit a check [POST /api/v1/checking/checks]

Submits a document for checking. After you upload a document, Acrolinx schedules the check. Once checking completes,
Acrolinx makes the results available. The following steps summarize how to use the checking API:

* Submit a check
* Poll for progress
* Download check results

To learn what file types Acrolinx supports, see the list of
[supported input types](https://support.acrolinx.com/hc/en-us/articles/10211264846482-Supported-Input-Types).
The same information is available in the checking capabilities.

+ Request (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token
            X-Acrolinx-Client: your_client_signature

    + Body

            // A minimal request declaring the format only:

            {
                "content": "text to check",                  // required
                "checkOptions": {
                    "contentFormat": "markdown",                 // recommended, default: auto
                },
            }

            // A minimal request using a document reference to tell the format:

            {
                "content": "text to check",                  // required
                "document": {                                // recommended, default: empty "document" object
                    "reference": "C:\\abc.md",              // recommended, used to determine the input format and correlate multiple checks of the same document
                }
            }


            // If a standard format is configured in Acrolinx, the minimal request is even shorter:

            {
                "content": "text to check",                  // required
            }

            // A request can be much more specific, this is the full set of attributes:

            {
                "content": "text to check",                  // required
                "contentEncoding": "base64",                 // optional, default: none = HTTP request encoding
                "checkOptions": {
                    "guidanceProfileId": "aud-1",                // optional, default: first guidance profile. optional target name/target id, default: detected by Automatic Target Assignment
                    "reportTypes": ["scorecard"],                // optional, default: scorecard
                    "contentFormat": "markdown",                 // optional, default: auto
                    "checkType": "batch",                        // optional, default: interactive
                                                                 // The available check types include:
                                                                 //   interactive =  an individual user checked a single file from an integration
                                                                 //   batch       =  an individual user checked multiple files from an integration
                                                                 //   baseline    =  an individual user initiated a check for a shared repository of files from a repository integration
                                                                 //   automated   =  a check of a single file initiated automatically (for example, by using a git hook)
                                                                 // To learn more about the available check types, [visit the Acrolinx coding guidance](https://github.com/acrolinx/acrolinx-coding-guidance/blob/main/topics/check-types.md).
                    "partialCheckRanges": [{ "begin": 10, "end": 20 }, { "begin": 40, "end": 70 }],   // makes the check a partial check
                    "batchId": "gen.clc.159203590"                      // only for batch checks; optional;
                },
                "document": {                               // optional, default: empty "document" object
                    "reference": "C:\\abc.md",              // optional integration known id hint e.g. a file name
                    "customFields": [                       // optional
                        {
                            "key": "field1",
                            "value": "value1"
                        },{
                            "key": "field2",
                            "value": "value2"
                        }
                    ]
                 },
                 "language": "en"                           // optional: force language for Target Assignment using
                                                            //           guidanceProfile.language.id codes (see
                                                            //           checking capabilities)
                                                            // default: target language if target is set in checkOptions.guidanceProfileId,
                                                            //          otherwise auto-detected
            }

+ Response 201 (application/json)

        {
          "data": {
            "id": "AB-153"
          },
          "links": {
            "result": "https://tenant.acrolinx.cloud/api/v1/checking/checks/AB-153",
            "cancel": "https://tenant.acrolinx.cloud/api/v1/checking/checks/AB-153"
          }
        }

+ Response 400 (application/json)

        {
          "error": {
            "detail": "The guidance profile doesn't exist or isn't available for the user id and language given.",
            "type": "content_goal",
            "title": "guidance profile doesn't exist",
            "status": 400
          },
          "links": {
          }
        }


## Check result [/api/v1/checking/checks/{id}]

### Check result guide

#### Ignore all issue occurrences
Every issue in the check result has the attribute `positionalInformation.hashes.issue`. Use this attribute to find all occurrences of an issue. Users can ignore all of these issues together.

The integration also remembers the `positionalInformation.hashes.issue` attribute after an ignore-all operation. This information lets you filter out all previously ignored occurrences of an issue after a recheck.

#### Replace all issue occurrences with a suggestion
Every issue in the check result has the attribute `positionalInformation.hashes.issue`. Use this attribute to find all occurrences of an issue.

To apply a suggestion to all occurrences of an issue, use the `groupId` attribute to find the corresponding suggestion.
If an occurrence of an issue doesn't have a suggestion with the same `groupId` or if the `groupId` is empty, then you can't replace it with a replace-all operation.

Note that not all occurrences of an issue always have the same suggestions. When this happens, the replace-all operation only applies to issues with the same suggestion.


### Poll check result [GET]

Polls the check result. Acrolinx either returns a progress response or the completed result. The URL for the request is in the "result" link of the submitted check.

NOTE: To optimize server memory, check results are removed from the server immediately after they are successfully retrieved. Ensure your integration stores the result locally if needed, as a second attempt to fetch the same Check ID will result in a `404 Not Found`.

If you don't want to view detailed check results, you can use `HEAD` requests to poll the check status. While the check is in progress, you'll receive the status code
202. There will also be a `Retry-After` header with a suggested retry delay.

+ Parameters
    + id: `AB-153` (string, required) - the check id

+ Request

    + Headers

            X-Acrolinx-Auth: your_access_token
            X-Acrolinx-Client: your_client_signature

+ Response 202 (application/json)

    + Headers

            Retry-After: 2

    + Body

            {
              "progress" : {
                "percent": 20,
                "message": "Waiting in queue",
                "retryAfter": "2"
              }
            }

+ Response 200 (application/json)

        Attention: which attributes the response contains depends on
        the configuration, request, and document.

        {
          "data":{
            "id": "AB-153",
            "checkOptions": {
                "guidanceProfileId": "aud_1",
                "guidanceProfileName": "Acrolinx Essentials",
                "languageId": "en",
                "termSets": [{
                    "displayName": "Switches"
                },
                {
                    "displayName": "Acrolinx"
                }],
                "reportTypes": ["scorecard", "termharvesting"],
                "contentFormat": "markdown",
                "checkType": "interactive",
                "partialCheckRanges": [{ "begin": "10", "end": "20" }, { "begin": "40", "end": "70" }],
                "confidential": false
            },
            "document": {
                "id": "283ab1e075f21a",
                # DRAFT ------START------
                "contentType": "E-Mail",
                # DRAFT ------END------
                "customFields": [
                    {
                        "displayName": "Project ID",
                        "key": "projectId",
                        "value": "Marketing Campaign",
                        "required": true
                    }
                ],
                "displayInfo": {
                    "reference": "abc.md"
                }
            },
            "quality": {
                "score": 81,
                "status": "red",
                "scoresByStrategy": [
                {
                  "id": "average",
                  "score": 81
                },
                {
                  "id": "minimum",
                  "score": 78
                }],
                "scoresByGoal": [
                {
                  "id": "CORRECTNESS",
                  "score": 83
                },
                {
                  "id": "CLARITY",
                  "score": 64
                },
                {
                  "id": "WORDS_AND_PHRASES",
                  "score": 78
                }],
                "metrics": [
                {
                  "id": "Clarity index",
                  "score": 100
                },
                {
                  "id": "Informality index",
                  "score": 47
                },
                {
                  "id": "Liveliness index",
                  "score": 50
                },
                {
                  "id": "Flesch Reading Ease",
                  "score": 36
                }]
            },
            "counts": {
                "issues": 4,
                "scoredIssues": 2, // **Since Acrolinx 2020.11**
                "sentences": 10,
                "words": 121
            },
            "goals": [{
                "id": "CORRECTNESS",
                "displayName": "Correctness",
                "color": "#00bfa5",
                "scoring": "required",
                "issues": 1
            },
            {
                "id": "CLARITY",
                "displayName": "Clarity",
                "color": "#ec407a",
                "scoring": "recommended",
                "issues": 2
            },
            {
                "id": "WORDS_AND_PHRASES",
                "displayName": "Words and Phrases",
                "color": "#ea80fc",
                "scoring": "required",
                "issues": 1
            }],
            "issues": [
                {
                    "goalId": "CORRECTNESS",
                    "guidelineId": "EN20111291451MK",
                    "internalName": "title_case_chicago",
                    "displayNameHtml": "Use Chicago style for the title case?",
                    "guidanceHtml": "<div class=\"shortHelp\" lang=\"en\" xml:lang=\"en\">\n<p>According to the <q>Chicago Manual of Style</q>, here's how you write titles:</p>\n<ul>\n<li>Capitalize the first word and the last word.</li>\n<li>Capitalize all \"main\" words.</li>\n<li>Don't capitalize articles and conjunctions (example: <q>a</q>, <q>and</q>).</li>\n<li>Don't capitalize prepositions independent of their length (example: <q>about</q>, <q>around</q>).</li>\n</ul>\n</div>",
                    "displaySurface": "zentense",
                    "canAddToDictionary": true,
                    "issueType": "actionable",   // possible values: actionable, analytical (since 2021.02)
                    "positionalInformation": {
                        "hashes": {
                            "issue": "BhKh3iaGBjB7Cw6M/GwrLQ==",
                            "environment": "vJ9eCVViEpIdM76h+5K/nA==",
                            "index": "hjlRLT0K+LlvlslKdNUlhw==1"
                        },
                        "matches": [{
                            "extractedPart": "zen",
                            "extractedBegin": 30,
                            "extractedEnd": 33,
                            "originalPart": "zen",
                            "originalBegin": 19247,
                            "originalEnd": 19255
                        }, {
                            "extractedPart": "te",
                            "extractedBegin": 33,
                            "extractedEnd": 35,
                            "originalPart": "&te;",
                            "originalBegin": 19250,
                            "originalEnd": 19254
                        },{
                            "extractedPart": "nse",
                            "extractedBegin": 35,
                            "extractedEnd": 38,
                            "originalPart": "nse",
                 "issueLocations": [
                        {
                            "locationId": "pageLocation",
                            "displayName": "Page 4",
                            "values": { "page": "4" }
                        }
                    ],
                    "suggestions": [
                        {
                            "surface": "sentence",
                            "groupId": "sentence",
                            // the replacements refer to the matches entry of the same Index
                            // null means, don't change, any other value including the empty string means, replace the match
                            "replacements": ["sen",null,"nce"],
                            "iconId":"preferred" // optional icon id for terminology issues, "preferred" or "admitted"
                        }
                  }],
                    "links":
                        {
                            "termContribution": "https://tenant.acrolinx.cloud/terminology/v7/rest/contribute",
                            "termContributionInteractive": "https://tenant.acrolinx.cloud/termcontribution.html?surface=@@base64:cXdlcnR5dWlvcA==&locale=en&language=en&userid=admin&context=@@base64:VGhpcyBzZW50ZW5jZSBoYXMgYSBxd2VydHl1aW9wLg==",
                            "addToDictionary": "https://tenant.acrolinx.cloud/api/v1/dictionary/submit",
                            "help":"https://tenant.acrolinx.cloud/htmldata/en/rules/help/title_case_chicago.html"
                        }
                },
                {
                    "goalId": "WORDS_AND_PHRASES",
                    "guidelineId": "b4a5192e-5f9e-4f10-a849-a16be4b9cb18",
                    "internalName": "term_flag",
                    "displayNameHtml": "<b>Illegal sublanguage variant</b> of preferred term",
                    "guidanceHtml": "<div class=\"guidance term\">\n\t<b>Domains</b>\n\t\t\t<br/><i>Switches</i>\n\t\t\t\t\t<br/>\n\t\t<b>Note</b>\n\t\t<br/>\n\t\tUse &#39;please&#39; in presale materials only. Do NOT use &#39;please&#39; in postsale material.\n\t</div>\n",
                    "canAddToDictionary": false,
                    "issueType": "actionable",
                    "displaySurface": "Please",
                    "positionalInformation": {
                        "hashes": {
                            "issue": "3qyt/AVxwNTOUQSuMA7brw==",
                            "environment": "TiwIFBwA6X920mDAezJTyQ==",
                            "index": "Lm9PqBGGm+tj21rt3pkpjA==1"
                        },
                        "matches": [{
                            "extractedPart": "Please",
                            "extractedBegin": 766,
                            "extractedEnd": 772,
                            "originalPart": "Please",
                            "originalBegin": 28223,
                            "originalEnd": 28229,
                        }],
                    },
                    "readOnly": false,
                    "issueLocations": [],
                    "suggestions": [
                        {
                            "surface": "blablub",
                            "icon": "https://tenant.acrolinx.cloud/tng/icons/preferred.svg",
                            "groupId": "2653",
                            "replacements": ["blablub" ]
                            }
                        }
                    ],
                    # DRAFT ------START------
                    "debug": {
                        "term": {
                            "surface": "please",
                            "status": "DEPRECATED",
                            "termSets": ["RA-Terms"],
                            "domains": ["RA-Terms"],
                            "variant": "legalVariantIllegal",
                        }
                    }
                    # DRAFT -------END-------
                },
                {
                    "goalId": "CLARITY",
                    "guidelineId": "EN40111231459",
                    "internalName": "en-clarity-medium",
                    "displayNameHtml": "Too complex? Your readers need a medium level of clarity. ",
                    "guidanceHtml": "",
                    "canAddToDictionary": false,
                    "issueType": "actionable",
                    "displaySurface": "Reports ... length",
                    "positionalInformation": {
                        "hashes": {
                            "issue": "E3OxJ3bFcfWLyAisUxufAA==",
                            "environment": "XVYQZVyCoFOr1TDeyXuMgg==",
                            "index": "accsS0dbn/3rafcbT9NJGw==1"
                        },
                        "matches": [{
                            "extractedPart": "Reports",
                            "extractedBegin": 1360,
                            "extractedEnd": 1367,
                            "originalPart": "Reports",
                            "originalBegin": 33173,
                            "originalEnd": 33180,
                        }, {
                            "extractedPart": "length",
                            "extractedBegin": 1749,
                            "extractedEnd": 1755,
                            "originalPart": "length",
                            "originalBegin": 33562,
                            "originalEnd": 33568,
                        }]
                    },
                    "suggestions": [],
                    "issueLocations": [],
                    "readOnly": false,
                    "debug": {
                        "penalty": 1234.0967741949999
                    },
                    "subIssues": [{
                        "goalId": "CLARITY",
                        "guidelineId": "EN92712627329",
                        "internalName": "phenomenon_embedded_or_complex_sentence",
                        "displayNameHtml": "Try to split up this sentence.",
                        "guidanceHtml": "<p>This sentence doesn't seem to flow smoothly. We found a few embedded phrases in there that could be messing with your flow somehow.</p>",
                        "canAddToDictionary": false,
                        "issueType": "actionable",
                        "displaySurface": "Reports ... length",
                        "positionalInformation": {
                            "hashes": {
                                "issue": "7s1nqUN96X+P6VY4FlfSQQ==",
                                "environment": "XVYQZVyCoFOr1TDeyXuMgg==",
                                "index": "++0c1Z/OQu1Mwzt0KpkYYA==1"
                            },
                            "matches": [{
                                "extractedPart": "Reports",
                                "extractedBegin": 1360,
                                "extractedEnd": 1367,
                                "originalPart": "Reports",
                                "originalBegin": 33173,
                                "originalEnd": 33180,
                            }, {
                                "extractedPart": "length",
                                "extractedBegin": 1749,
                                "extractedEnd": 1755,
                                "originalPart": "length",
                                "originalBegin": 33562,
                                "originalEnd": 33568,
                            }]
                        },
                        "suggestions": [],
                        "issueLocations": [],
                        "readOnly": false,
                        "debug": {
                            "penalty": 320.0
                        }
                    }, {
                        "goalId": "CLARITY",
                        "guidelineId": "EN12771268128",
                        "internalName": "phenomenon_passive",
                        "displayNameHtml": "The active voice is usually clearer.",
                        "guidanceHtml": "<p>This one could do with a bit of pep. It's probably because it feels kind of passive. We love it when you're assertive.</p>",
                        "canAddToDictionary": false,
                        "issueType": "actionable",
                        "displaySurface": "was first seen",
                        "positionalInformation": {
                            "hashes": {
                                "flag": "dg+ih1XodWeL7lJ/wo17QQ==",
                                "environment": "XVYQZVyCoFOr1TDeyXuMgg==",
                                "index": "fOJLASZHiwnwcJWcfbkXnw==1"
                            },
                            "matches": [{
                                "extractedPart": "was",
                                "extractedBegin": 1406,
                                "extractedEnd": 1409,
                                "originalPart": "was",
                                "originalBegin": 33219,
                                "originalEnd": 33222
                            }, {
                                "extractedPart": "first",
                                "extractedBegin": 1410,
                                "extractedEnd": 1415,
                                "originalPart": "first",
                                "originalBegin": 33223,
                                "originalEnd": 33228
                            }, {
                                "extractedPart": "seen",
                                "extractedBegin": 1416,
                                "extractedEnd": 1420,
                                "originalPart": "seen",
                                "originalBegin": 33229,
                                "originalEnd": 33233
                            }]
                        },
                        "suggestions": [],
                        "issueLocations": [],
                        "readOnly": false,
                        "debug": {
                            "penalty": 40.0
                        }
                    }]
                },
                {
                    "goalId": "CLARITY",
                    "guidelineId": "EN85291241038",
                    "internalName": "guideline_FleschReadingEaseAsGuideline",
                    "displayNameHtml": "<span><b>Flesch Reading Ease: 47</b><br>Flesch Reading Ease is a classic readability metric.</span>",
                    "guidanceHtml": "",
                    "canAddToDictionary": false,
                    "issueType": "analytical",
                    "displaySurface": "I",
                    "issueType": "analytical",
                    "positionalInformation": {
                        "hashes": {
                            "issue": "l5wwcDu9O3IhYnnnlx6m/2e+IMTnPtkA6T3YoeqABMo=",
                            "environment": "lw/i85HTXLCY6KMk/8eOPc1vt5qB79eoy3RG1AEeQMI=",
                            "index": "9PAShJ4SjFdW4YoLGfp1WFzdUnXe9ZCP2rUI30VscFE==1"
                        },
                        "matches": [
                            {
                                "extractedPart": "I",
                                "extractedBegin": 0,
                                "extractedEnd": 1,
                                "originalPart": "I",
                                "originalBegin": 1542,
                                "originalEnd": 1543
                            }
                        ]
                    },
                    "readOnly": false,
                    "issueLocations": [],
                    "suggestions": [],
                    "subIssues": [],
                    "links": {
                        "help": "https://tenant.acrolinx.cloud/htmldata/en/rules/help/voice.FleschReadingEaseAsGuideline.html"
                    }
                }
            ],
            "keywords": {
                "links":{
                    "getTargetKeywords": "https://tenant.acrolinx.cloud/services/v1/rest/findability/targetKeywords?contextId=C%3A%5CUsers%5Cgrabowski%5CDesktop%5Ccloud-linguistic-smoketest.docx",
                    "putTargetKeywords": "https://tenant.acrolinx.cloud/services/v1/rest/findability/targetKeywords?contextId=C%3A%5CUsers%5Cgrabowski%5CDesktop%5Ccloud-linguistic-smoketest.docx"
                },
                "discovered": [{
                    "keyword": "Clarity card",
                    "sortKey": "10",
                    "density": 0.2546269436736127,
                    "count": 4,
                    "prominence": 0.0,
                    "occurrences": [{
                        "matches": [
                        // ...
                        ]
                    }],
                    "warnings": []
                }],
                "target": []
            },
            "embed":[{ // While the below keys represent the current implementation, they can change without notice
                "key": "timeStarted",
                "value": "2018-11-23T07:29:10.979Z[UTC]"
            },{
                "key": "score",
                "value": "84"
            },{
                "key": "status",
                "value": "green"
            },{
                "key": "scorecardUrl",
                "value": "https://tenant.acrolinx.cloud/services/output/en/oi5ilqippevjh2cdyn3hyldiwa_report.html"
            }],
            // DRAFT ------START------
            "addonInfo": [
                {
                    "id": "mightyAddon",
                    "title": "Mighy Addon by Cool Corp.",
                    "iconClass": "search-icon",
                    "iconUrl": "...",
                    "url": "https://mighy.cool.com/addon?fancyId=12345"
                }
            ],
            // DRAFT -------END-------
            "reports": {
                "scorecard": {
                    "displayName":"Score Card",
                    "link": "https://tenant.acrolinx.cloud/output/en/abcdef_1_report.html",
                    "linkAuthenticated": "https://tenant.acrolinx.cloud/output/en/abcdef_1_report.html?apikey=hfhfzhfhrz"
                },
                "termharvesting": {
                    "displayName": "Term Harvesting",
                    "link": "https://tenant.acrolinx.cloud/output/en/termharvesting_1.xml",
                    "linkAuthenticated": "https://tenant.acrolinx.cloud/output/en//termharvesting_1.xml?apikey=tfhzzhfhrz"
                },
                // only if a batch Id was given in the initial request
                "contentAnalysisDashboard": {
                    "displayName": "Content Analysis Dashboard",
                    "link": "https://tenant.acrolinx.cloud/batch/dccerthjj",
                }
            },
            "dictionaryScopes": ["language", "guidanceProfile", "document"]
          },
          "links": {
          }
        }

+ Response 400 (application/json)

        {
          "error": {
            "message": "Custom field values are missing",
            "type": "custom_fields_incorrect",
            "title": "Custom field values are incomplete.",
            "documentId": "3487ahgfh5fg-fg3",
            "validationDetails": [
                {
                    "title": "Custom field is required.",
                    "constraint": "Custom field \"Field\" must not be empty.",
                    "attributePath": "document.customFields.Field",
                    "detail": "Cannot set custom field \"Field\" as it is required and its value is empty.",
                    "invalidValue": null,
                    "possibleValues": ["Correct Value 1","Correct Value 2"],
                    "type": "Required"
                }
            ],
            "status": 400
          },
          "links": {
          }
        }

+ Response 400 (application/json)

        // if any of the given custom fields is invalid, a detailed error information is given.
        {
          "error": {
            "detail": "The value for document custom field \"Field\" cannot be \"Wrong Value\".",
            "type": "custom_fields_incorrect",
            "title": "Custom field values are incorrect",
            "documentId": "3487ahgfh5fg-fg3",
            "validationDetails": [
                {
                    "title": "Custom field of invalid value.",
                    "constraint": "Custom field \"Field\" must not be \"Wrong Value\".",
                    "attributePath": "document.customFields.Field",
                    "detail": "Cannot set custom field \"Field\" as it is required and its value is empty.",
                    "invalidValue": "Wrong Value",
                    "possibleValues": ["Correct Value 1","Correct Value 2"],
                    "type": "InvalidValue" // InvalidValue, InvalidField, Required, Readonly, Inconsistent
                }
            ],
            "status": 400
          }
        }

+ Response 422 (application/json)

        // the document can't be processed by the platform
        {
          "error": {
            "detail": "<reason why the document could not be processed>",
            "type": "check_failed",
            "title": "Check failed",
            "status": 422
          }
        }


### Poll check result [HEAD]

For response status codes and headers, visit the section [GET](#reference/checking-api/check-result/poll-check-result).

+ Parameters

    + id: `AB-153` (string, required) - the check id

+ Request

    + Headers

            X-Acrolinx-Auth: your_access_token
            X-Acrolinx-Client: your_client_signature

+ Response 202 (application/json)

    The check is in progress

    + Headers

            Retry-After: 2

+ Response 200 (application/json)

    The check is done.

    + Headers

+ Response 400 (application/json)

    The check failed because of an error in the request.

    + Headers

+ Response 422 (application/json)

    Acrolinx can't process the file.

    + Headers


### Cancel check [DELETE]

        Cancels a check. Users can only cancel checks that they submitted. The URL for the request is in the "cancel" link of the submitted check.

+ Parameters
    + id: `AB-153` (string, required) - the check id

+ Request

    + Headers

            X-Acrolinx-Auth: your_access_token
            X-Acrolinx-Client: your_client_signature

+ Response 200 (application/json)

        {
          "data": {
            "id": "153"
          }
        }


## Get link to Content Analysis Dashboard [GET /api/v1/checking/{batchId}/contentanalysis]

Returns the links to the human readable Content Analytics Dashboard, which aggregates information of all checks belonging to the given batch id. Requires the reporting read-only privilege. The link with an API token contains a new token with the reporting read-only privilege.

+ Parameters
    + batchId: `XYZ-10-22-33` (string, required) - the batch check id

+ Request

    + Headers

            X-Acrolinx-Auth: your_access_token
            X-Acrolinx-Client: your_client_signature


+ Response 200 (application/json)

        {
            "links": {},
            "data": {
                "links": [
                    {
                        "linkType": "withoutAccessToken",
                        "link": "https://tenant.acrolinx.cloud/analytics/dashboard/app/entry/run.jsp?jrd_resext=%7Bactive%3A0%2Creslst%3A%5B%7Bname%3A%22%2FAcrolinxReports%2Fstandard%2FContent+Analysis.dsh%22%2C%22param_page%22%3Afalse%2Cver%3A-1%2C%22dsh_params%22%3A%5B%7B%22jrd_params%22%3A%7B%22BatchId%22%3A%22_nice_batch_id_88-xyz%22%2C%22CsBaseUrl%22%3A%22http%3A%2F%2Flocalhost%3A8031%22%2C%22CsOutputPath%22%3A%22%2Foutput%22%7D%7D%5D%7D%5D%7D&jrd_userinfo=%7B%22prefer%22%3A%7B%22rpt_lang%22%3A%22en%22%2C%22enableNLS%22%3Atrue%7D%7D&jrs.language=en"
                    },
                    {
                        "linkType": "withAccessToken",
                        "link": "https://tenant.acrolinx.cloud/analytics/dashboard/app/entry/run.jsp?jrd_resext=%7Bactive%3A0%2Creslst%3A%5B%7Bname%3A%22%2FAcrolinxReports%2Fstandard%2FContent+Analysis.dsh%22%2C%22param_page%22%3Afalse%2Cver%3A-1%2C%22dsh_params%22%3A%5B%7B%22jrd_params%22%3A%7B%22BatchId%22%3A%22_nice_batch_id_88-xyz%22%2C%22CsBaseUrl%22%3A%22http%3A%2F%2Flocalhost%3A8031%22%2C%22CsOutputPath%22%3A%22%2Foutput%22%7D%7D%5D%7D%5D%7D&jrd_userinfo=%7B%22prefer%22%3A%7B%22rpt_lang%22%3A%22en%22%2C%22enableNLS%22%3Atrue%7D%7D&jrs.language=en&apikey=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG11ZCI6ImFjcm9saW54OjA4MTEwYThjNzI3MjQzYTMiLCJuYmYiOjE1MDM5MjcyMzksImlzcyI6ImFjcm9saW54OjA4MTEwYThjNzI3MjQzYTM6NWQyNTQ2NWI5ZTA3NDNiZiIsImV4cCINjYwNTYzOSwidG9rZW5UeXBlIjoidXNlciIsImlhdCI6MTUwNDAxMzYzOSwianRpIjoiMmFmOTQzOWIzZDgyNzMwODAEyMGRiZmRlMmYifQ.Lj0chsnnRTX7IevJNyWMMlCviA6ecYAQ0kacy5EGQz0"
                    },
                    {
                        "linkType": "shortWithAccessToken",
                        "link": "http://localhost:8031/api/batch/123?apikey=eyJ0eXAiOiJKV1QiLCOiJhY3JvbGlueCIsInByaXZpbGVnZXMiOlsiQ2hlY2tpbmdBbmRDbGllbnRzLmRvd25sb2FkUmVwb3J0cyJdLCJuYmYiOjE1Mzc5NTQzMjksImlzcyI6ImFjcm9saW54OjA4MTEwYThjNzI3MjQzYTMiLCJleHAiOjE1MzgxMjcxMjksInRva2VuVHlwZSI6InByaXZpbGVnZXMiLCJpYXQi3MjksImp0aSI6IlZRTVNFUzc0SlRCR0JFVFMyWTVBRjJBU1RNIn0.ltac_6JK0s_uODrqrK3TkaUsZiXfrkamo&X-Acrolinx-Client-Locale=en"
                    },
                    {
                        "linkType": "shortWithoutAccessToken",
                        "link": "http://localhost:8031/api/batch/123?X-Acrolinx-Client-Locale=en"
                    }
                ]
            }
        }

# Group User API

In the User API, Acrolinx defines a user as an entity that has the following:
* An id
* A username
* A fullName
* Custom properties (set by the integration).

You're _required_ to provide user information for the following:
* Interactive integrations: When you sign in to the Sidebar, you enter your user information. This creates an access token for the signed-in user.
* Embedded (CMS) integrations (that use an API token): When you sign in to Acrolinx, you need to enter your custom user information. Use this API to generate an API token for the user that’s signed in.

Security:
* A user can read and update their own data.
* Only users with sufficient privileges (admin, for example) can read or update other users' data.

**Note:** Before you get started with the User API, review the [authentication and authorization](https://acrolinxapi.docs.apiary.io/#introduction/authentication-and-authorization) requirements. 

## User resource [/api/v1/user]

### Get all users [GET /api/v1/user{?sort,page,per_page,username,fullName,roles}]

This request retrieves a list of all users in the order of creation.

**Searching or filtering**

- Use the `username` and `fullName` parameters to search or filter users.
- The `username` and `fullName` query parameters are limited to 255 characters, are optional, and can't be `null`.
- If the `username` and `fullName` parameters are set, the API will list users that match both parameters.
- Use the `roles` parameter to filter users by multiple role ids.
- Invalid role ids will return an empty list.

**Sorting**

If you use the `sort` query parameter, you can only sort the list of users by 1 field.
To show the list in ascending or descending order, add a `+` or `-`, respectively.

**Sorting notes:**

- You can only sort by 1 field.
- A query parameter can be any length and can include the order direction prefixes "+" or "-".
- A query parameter cannot be empty or include spaces.
- A query parameter can accept a mix of characters.
- By default, the list appears in ascending order.
- The list is also sorted by `username`, unless `username` is already the primary sort column.
- Other sort columns include: `fullName`, `createdOn`, `lastIntegrationAccess`, `checkingFrequency`, `licenseType`, `licenseStatus`, and `customFields.{key}`.
- The query parameter `licenseType` sorts by two fields: `licenseType` and `licenseStatus`.
- To sort by a custom field, the sort value needs to include `customFields`, `.`, and the `{key}`. The key is the name of the custom field.

When you sort by `customFields` in ascending order, empty `customFields` values will appear at the beginning of the list. If you sort
in descending order, empty values will appear at the end of the list.

To make sure that the sorting behavior for custom fields is consistent, the following special characters are sortable: `` !@$^*()_+-=,./;'[]<>?:|~` ``
If you use any additional special characters, the sorting behavior may be inconsistent.

So that the `+` character encoded to `%2B` stays valid, you have to encode the query parameters according
to [encodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent). 
You can always leave out the `+` character, because the user list appears in ascending order by default. 

**Pagination**

For a better overview, you might want to view the list of users in pages instead of as one long list.
To request a paginated response, add the query parameters `page` and `per_page`. 
You'll need to set the `page` parameter. The page count always starts at `1`.
By default, `per_page` is set to `10`. You can display as many as 500 users per page. This is an optional parameter. 

If you request a paginated response, Acrolinx will add the following header values:

| Header                     | Description                                     |
|----------------------------|-------------------------------------------------|
| `X-Acrolinx-Page`          | The index of the current page, starting at `1`. |
| `X-Acrolinx-Next-Page`     | The index of the next page.                     |
| `X-Acrolinx-Previous-Page` | The index of the previous page.                 |
| `X-Acrolinx-Total-Pages`   | The total number of pages.                      |
| `X-Acrolinx-Total`         | The total number of items.                      |

In addition to the header values, the response object also contains a few URLs
within the `links` object:

| Relation | Description                       |
|----------|-----------------------------------|
| `next`   | The URL to get the next page.     |
| `prev`   | The URL to get the previous page. |
| `first`  | The URL to get the first page.    |
| `last`   | The URL to get the last page.     |

If there aren't any next or previous pages, you won't see the `next` and `prev` links.
For example, when you view page 1, you won't see a `prev` link because there's no page 0. 
This is also the case for the values in the headers.

**Note:** When you switch to the next or previous page, you'll see the current paginated view at the time of the API call. 
This view will also reflect any changes to the underlying data source. Say you're on page 2 of 10 with 10 records per page but  
then you decide to delete 10 users before you call the API to fetch page 3. Now when you switch to page 3, the response will show page 3 of 9.

The example response includes the pagination URLs and query parameters in the `links` object so you know what to expect. 

**Dynamically include or exclude nested data**

If you manage a large number of users, you can use the query parameters `includeCustomField` and `excludeProperties` to filter nested data.

By default, all custom fields are nested in the user model.
Use the `includeCustomField` parameter to limit the returned fields to those that match the key passed in the parameter value.
This parameter is helpful if you want to fetch a specific set of custom fields to reduce data transfer.
To include more than one custom field, add `&includeCustomField={Key}` to the request N times.
To exclude all custom fields, use the parameter `&excludeCustomFields=true`. This takes priority over any
`includeCustomField` parameters that are present, and will always result in no custom fields being returned.

+ Parameters

    + username (string, optional) - Optional query parameter for searching by username.
    + fullName (string, optional) - Optional query parameter for searching by full name.
    + sort (enum[string], optional) - Optional query parameter for sorting by an attribute. 
            
        + Prefix the field with:
            + **"+"** for ascending order, or
            + **"-"** for descending order. 
        + **Note:** 
            + Omitting a prefix will sort in ascending order.
            + Use `customFields.{key}` to sort by custom fields. `{key}` is the name of the custom field.

        + Default: username
        + Members
            + `username`
            + `fullName`
            + `createdOn`
            + `lastIntegrationAccess`
            + `checkingFrequency`
            + `licenseType`
            + `licenseStatus`
            + `customFields.{key}`

    + page (number, optional) - Optional query parameter for pagination
    + per_page (number, optional) - Optional query parameter for sizing a page
        + Default: `10`
    + roles (array[string], optional) - Optional query parameter to filter by multiple role ids

+ Request Get a list of all users (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (Pagination)
        + data (array[User])

    + Body

            {
                "links": {
                    "prev": "https://tenant.acrolinx.cloud/api/v1/user?page=2&per_page=2&sort=username&fullName=Fred Freelancer&username=fred",
                    "next": "https://tenant.acrolinx.cloud/api/v1/user?page=4&per_page=2&sort=username&fullName=Fred Freelancer&username=fred",
                    "first": "https://tenant.acrolinx.cloud/api/v1/user?page=1&per_page=2&sort=username&fullName=Fred Freelancer&username=fred",
                    "last": "https://tenant.acrolinx.cloud/api/v1/user?page=60&per_page=2&sort=username&fullName=Fred Freelancer&username=fred"
                },
                "data": [
                    {
                        "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                        "username": "fred",
                        "fullName": "Fred Freelancer",
                        "createdOn": "2021-04-15T15:00:26.495Z",
                        "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                        "licenseType": "named",
                        "licenseStatus": "inactive",
                        "activeTokenId": "",
                        "checkingFrequency": "infrequent",
                        "properties" : {
                            "customkey": "customvalue",
                        },
                        "roles": [
                            {
                                "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                                "name": "Term Contributor"
                            },
                            {
                                "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                                "name": "Term Browser Administrator"
                            }
                        ],
                        "idpUser": true,
                        "staffUser": true,
                        "rolesSetByIdp": false,
                        "customFields": [
                            {
                                "key": "Department",
                                "displayName": "Department",
                                "inputType": "optional",
                                "type": "list",
                                "value": "Example Department",
                                "possibleValues": [
                                    "Example Department"
                                ]
                            }
                        ]
                    },
                    {
                        "id": "fd3eaa89-a6b7-463a-ba12-b7ded410bda0",
                        "username": "franz",
                        "fullName": "Franz Hubendobler",
                        "createdOn": "2021-02-23T17:24:01.131Z",
                        "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                        "licenseType": "builtin",
                        "licenseStatus": "active",
                        "activeTokenId": "uqlyxi3cdxrdqn7bzwdfffyvzr",
                        "checkingFrequency": "infrequent",
                        "properties" : {
                            "customkey": "customvalue",
                        },
                        "roles": [
                            {
                                "id": "898a7c32-2c39-4cde-becb-16f22243e9b8",
                                "name": "Analytics Read-Only User"
                            }
                        ],
                        "idpUser": true,
                        "staffUser": true,
                        "rolesSetByIdp": false,
                        "customFields": [
                            {
                                "key": "Department",
                                "displayName": "Department",
                                "inputType": "optional",
                                "type": "list",
                                "value": "Example Department",
                                "possibleValues": [
                                    "Example Department"
                                ]
                            }
                        ]
                    }
                ]
            }

+ Request Get a list of all users sorted by license type in ascending order (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (Pagination)
        + data (array[User])

    + Body

            {
                "links": {},
                "data": [
                    {
                        "id": "5894f2bb-5b34-4874-bc40-ec64e9a4ca63",
                        "username": "analyticsReadOnlyUser",
                        "fullName": "",
                        "createdOn": "2021-10-07T08:40:53.646Z",
                        "activeTokenId": "",
                        "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                        "licenseType": "builtin",
                        "licenseStatus": "active",
                        "checkingFrequency": "infrequent",
                        "roles": [
                            {
                                "id": "898a7c32-2c39-4cde-becb-16f22243e9b8",
                                "name": "Analytics Read-Only User",
                                "default": false
                            }
                        ],
                        "idpUser": true,
                        "staffUser": true,
                        "rolesSetByIdp": false,
                        "properties": {
                            "Segmentation.xml.DTDs": ""
                        },
                        "customFields": [
                            {
                                "key": "Department",
                                "displayName": "Department",
                                "inputType": "optional",
                                "type": "list",
                                "value": "Example Department",
                                "possibleValues": [
                                    "Example Department"
                                ]
                            }
                        ]
                    },
                    {
                        "id": "c85030fd-2e03-4c69-9946-0b4f5689522c",
                        "username": "termcontribution",
                        "fullName": "",
                        "createdOn": "2021-10-07T08:40:53.642Z",
                        "activeTokenId": "",
                        "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                        "licenseType": "builtin",
                        "licenseStatus": "inactive",
                        "checkingFrequency": "infrequent",
                        "roles": [
                            {
                                "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                                "name": "Term Contributor",
                                "default": false
                            }
                        ],
                        "idpUser": true,
                        "staffUser": true,
                        "rolesSetByIdp": false,
                        "properties": {
                            "Segmentation.xml.DTDs": ""
                        },
                        "customFields": [
                            {
                                "key": "Department",
                                "displayName": "Department",
                                "inputType": "optional",
                                "type": "list",
                                "value": "Example Department",
                                "possibleValues": [
                                    "Example Department"
                                ]
                            }
                        ]
                    },
                    {
                        "id": "bb284474-e107-413e-9c15-d813ed7209e9",
                        "username": "fred",
                        "fullName": "Fred Freelancer",
                        "createdOn": "2021-10-21T11:52:36.912Z",
                        "activeTokenId": "touxmkywwmu5vk6nyqto2m75x6",
                        "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                        "licenseType": "named",
                        "licenseStatus": "active",
                        "checkingFrequency": "infrequent",
                        "roles": [
                            {
                                "id": "8c66c4e2-174a-4f77-b8d4-71bfa9ca4d2e",
                                "name": "Author",
                                "default": false
                            },
                            {
                                "id": "bc5c91f3-fae1-49f7-8d60-d325077c6ef9",
                                "name": "Super Administrator",
                                "default": false
                            }
                        ],
                        "idpUser": true,
                        "staffUser": true,
                        "rolesSetByIdp": false,
                        "properties": {
                            "Segmentation.xml.DTDs": ""
                        },
                        "customFields": [
                            {
                                "key": "Department",
                                "displayName": "Department",
                                "inputType": "optional",
                                "type": "list",
                                "value": "C",
                                "possibleValues": [
                                    "Example Department"
                                ]
                            }
                        ]
                    },
                    {
                        "id": "0593c6b4-99d9-4d43-886b-f67cb66df7ed",
                        "username": "franz",
                        "fullName": "Franz Hubendobler",
                        "createdOn": "2021-11-01T07:31:18.365Z",
                        "activeTokenId": "",
                        "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                        "licenseType": "named",
                        "licenseStatus": "inactive",
                        "checkingFrequency": "infrequent",
                        "roles": [
                            {
                                "id": "8c66c4e2-174a-4f77-b8d4-71bfa9ca4d2e",
                                "name": "Author",
                                "default": false
                            }
                        ],
                        "idpUser": true,
                        "staffUser": true,
                        "rolesSetByIdp": false,
                        "properties": {
                            "Segmentation.xml.DTDs": ""
                        },
                        "customFields": [
                            {
                                "key": "Department",
                                "displayName": "Department",
                                "inputType": "optional",
                                "type": "list",
                                "value": "B",
                                "possibleValues": [
                                    "Example Department"
                                ]
                            }
                        ]
                    }
                ]
            }

+ Response 400 (application/json)

        // when the sort query parameter uses an invalid field name
        {
            "links": {},
            "error": {
                "reference": "b4c323ab-413b-4bf5-be60-93e13c3aad93",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Couldn't parse 'sort' query parameter",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "detail": "sort param must not be null",
                        "invalidValue": "null"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the field name is omitted in the sort query parameter
        {
            "links": {},
            "error": {
                "reference": "b4c323ab-413b-4bf5-be60-93e13c3aad93",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Pattern",
                        "detail": "must match \"[+-]?.+\"",
                        "invalidValue": "+"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the per_page parameter exceeds the 500 per page limit
        {
            "links": {},
            "error": {
                "reference": "196f8b88-493c-46d7-b7bc-5da32d0a58d7",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                {
                    "title": "Validation error",
                    "constraint": "Range",
                    "detail": "must be between 1 and 500",
                    "invalidValue": "900"
                }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the page parameter has an invalid value such as 0 or negative number
        {
            "links": {},
            "error": {
                "reference": "b2045b7f-1dce-49e7-880a-93874f427554",
                "detail": "Invalid page request attribute, it must be greater than zero",
                "type": "client",
                "title": "Bad Request",
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the custom field name cannot be found
        {
            "links": {},
            "error": {
                "reference": "1095ac3c-4418-467d-930e-d517b8e34beb",
                "detail": "Telephone is not a valid user custom sortable field",
                "type": "client",
                "title": "Bad Request",
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the custom field name is null or empty
        {
            "links": {},
            "error": {
                "reference": "1095ac3c-4418-467d-930e-d517b8e34beb",
                "detail": "customFields cannot be null or empty.",
                "type": "client",
                "title": "Bad Request",
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 404 (application/json)

        // when the page parameter has a non-numeric value, which is invalid
        {
            "links": {},
            "error": {
                "reference": "f1926760-f2e7-4af7-a3a6-f274bcb9a00f",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

### Get a user [GET /api/v1/user/{id}]

This request returns information about a user.
The information includes the user id, username, the user's full name, the date the user was created, the last time the user accessed an integration, checking frequency, tenant ID, token ID, license type, and license status.
You'll also see properties, roles, and custom fields.

+ Parameters

    + id: `eb323701-839f-4998-b56e-3e20c70259c5` (string, required) - UUID of the user, unique identifier

+ Request Get specified user by id (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "Fred Freelancer",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "uqlyxi3cdxrdqn7bzwdfffyvzr",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                            "name": "Term Contributor"
                        },
                        {
                            "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                            "name": "Term Browser Administrator"
                        }
                    ],
                    "idpUser": true,
                    "staffUser": true,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        }
                    ]
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to fetch users
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the user couldn't be identified by its *id* in the database
        {
        "links": {},
            "error": {
                "reference": "652b5c86-de20-4629-9df6-84265f2722ec",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }


### Get a user (self) [GET /api/v1/user/self]

This is an alternative way to get information about the current user (authorized in the request).

+ Request Get current user (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "Fred Freelancer",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "uqlyxi3cdxrdqn7bzwdfffyvzr",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                            "name": "Term Contributor"
                        },
                        {
                            "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                            "name": "Term Browser Administrator"
                        }
                    ],
                    "idpUser": true,
                    "staffUser": true,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        }
                    ]
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 404 (application/json)

        // when the user couldn't be identified by its *id* in the database
        {
        "links": {},
            "error": {
                "reference": "652b5c86-de20-4629-9df6-84265f2722ec",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

### Create a user [POST /api/v1/user]

**Note:**

- The username needs to be unique and is limited to 255 characters.
- The `fullName` field is limited to 255 characters (optional).
- The license type can either be "named" or "concurrent" (optional).
- You need `UserAndRoles.editUser` privileges to perform this request.

**Password requirements**

If you want to create a user, the password field is required.
Your password needs to meet the following requirements:

- Composed of ASCII printable characters
- Include at least 1 lowercase letter
- Include at least 1 uppercase letter
- Include at least 1 digit
- Include at least 1 special character
- At least 10 characters long
- No more than 64 characters long

**Be very careful in the following cases:**
- Federated authentication is enabled:
  - Users are created automatically with federated authentication.
  - Only users created by the identity provider can sign in to Acrolinx.
  - Users that you create with the API can only be used for automation. For example, interactions with the Acrolinx API.


+ Request Create a user (application/json)

     This will create a new user if you add a username, fullName, and password to the request.

    **Note:** By default, Acrolinx will automatically assign the user the license type `named` and the role `Author`.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (CreateUser)

    + Body

            {
                "username": "fred",
                "fullName": "Fred Freelancer",
                "password": "P@ssW0rd12345!"
            }

+ Response 201 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "Fred Freelancer",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "8c66c4e2-174a-4f77-b8d4-71bfa9ca4d2e",
                            "name": "Author"
                        }
                    ],
                    "idpUser": false,
                    "staffUser": false,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        }
                    ]
                }
            }

+ Response 400 (application/json)

        // when the request format is invalid
        {
            "links": {},
            "error": {
                "detail": "Unexpected character ....",
                "type": "client",
                "title": "Could not parse request body.",
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2021.05
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Size",
                        "attributePath": "password",
                        "detail": "size must be between 1 and 128",
                        "invalidValue": "simple"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "attributePath": "password",
                        "detail": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "invalidValue": "not a secure password"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password is omitted starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotEmpty",
                        "attributePath": "password",
                        "detail": "must not be empty",
                        "invalidValue": ""
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the licenseType is invalid
        {
            "links": {},
            "error": {
                "reference": "f04a1a1e-0046-4b86-b9c3-da491d3343b5",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Deserialization error",
                        "constraint": "Must be one of [NAMED, CONCURRENT, BUILTIN].",
                        "attributePath": "licenseType",
                        "detail": "Cannot deserialize enum 'LicenseType' from value 'asd'. Possible values are [NAMED, CONCURRENT, BUILTIN].",
                        "invalidValue": "asd",
                        "possibleValues": [
                            "NAMED",
                            "CONCURRENT",
                            "BUILTIN"
                        ]
                    }
                ],
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to create users
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 409 (application/json)

        // when the user was created more than once
        {
        "links": {},
            "error": {
                "reference": "a159c153-e99b-4d49-9987-ca457670ef86",
                "detail": "Licensing error (Invalid user id (message ID #2): A user with the name 'fred' already exists. Please provide a different user name or spell the user name appropriately.)",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

+ Response 500 (application/json)

        // when an unspecified error occurs
        {
            "links": {},
            "error": {
                "reference": "4f356c86-aac1-4cae-8d78-518aea6cebe0",
                "detail": "An unspecific server error occurred. Details may be found in the Acrolinx log files.",
                "type": "server",
                "title": "Unspecific server error",
                "status": 500
            }
        }


+ Request Create a user with specified license type (application/json)

    This request will create a new user with the `named` license type explicitly specified in the request model.

    **Note:** Acrolinx will automatically assign the default role `Author` to the user.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (CreateUser)

    + Body

            {
                "username": "fred",
                "fullName": "Fred Freelancer",
                "password": "P@ssW0rd12345!",
                "licenseType": "named"
            }

+ Response 201 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "Fred Freelancer",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "8c66c4e2-174a-4f77-b8d4-71bfa9ca4d2e",
                            "name": "Author"
                        }
                    ],
                    "idpUser": false,
                    "staffUser": false,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        }
                    ]
                }
            }

+ Response 400 (application/json)

        // when the request format is invalid
        {
            "links": {},
            "error": {
                "detail": "Unexpected character ....",
                "type": "client",
                "title": "Could not parse request body.",
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2021.05
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Size",
                        "attributePath": "password",
                        "detail": "size must be between 1 and 128",
                        "invalidValue": "simple"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "attributePath": "password",
                        "detail": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "invalidValue": "not a secure password"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password is omitted starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotEmpty",
                        "attributePath": "password",
                        "detail": "must not be empty",
                        "invalidValue": ""
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the licenseType is invalid
        {
            "links": {},
            "error": {
                "reference": "f04a1a1e-0046-4b86-b9c3-da491d3343b5",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Deserialization error",
                        "constraint": "Must be one of [NAMED, CONCURRENT, BUILTIN].",
                        "attributePath": "licenseType",
                        "detail": "Cannot deserialize enum 'LicenseType' from value 'asd'. Possible values are [NAMED, CONCURRENT, BUILTIN].",
                        "invalidValue": "asd",
                        "possibleValues": [
                            "NAMED",
                            "CONCURRENT",
                            "BUILTIN"
                        ]
                    }
                ],
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to create users
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 409 (application/json)

        // when the same user is created more than once
        {
        "links": {},
            "error": {
                "reference": "a159c153-e99b-4d49-9987-ca457670ef86",
                "detail": "Licensing error (Invalid user id (message ID #2): A user with the name 'fred' already exists. Please provide a different user name or spell the user name appropriately.)",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

+ Response 500 (application/json)

        // when there's an unspecified error
        {
            "links": {},
            "error": {
                "reference": "4f356c86-aac1-4cae-8d78-518aea6cebe0",
                "detail": "An unspecific server error occurred. Details may be found in the Acrolinx log files.",
                "type": "server",
                "title": "Unspecific server error",
                "status": 500
            }
        }

+ Request Create a user with specified roles (application/json)

    This request will create a new user with specified roles.

    + Attributes (CreateUser)

    + Body

            {
                "username": "fred",
                "fullName": "Fred Freelancer",
                "password": "P@ssW0rd12345!",
                "roles": [
                    {
                        "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                        "name": "Term Contributor"
                    },
                    {
                        "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                        "name": "Term Browser Administrator"
                    }
                ]
            }

+ Response 201 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "Fred Freelancer",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                            "name": "Term Contributor"
                        },
                        {
                            "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                            "name": "Term Browser Administrator"
                        }
                    ],
                    "idpUser": false,
                    "staffUser": false,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        }
                    ]
                }
            }

+ Response 400 (application/json)

        // when the request format is invalid
        {
            "links": {},
            "error": {
                "detail": "Unexpected character ....",
                "type": "client",
                "title": "Could not parse request body.",
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2021.05
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Size",
                        "attributePath": "password",
                        "detail": "size must be between 1 and 128",
                        "invalidValue": "simple"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "attributePath": "password",
                        "detail": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "invalidValue": "not a secure password"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password is omitted starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotEmpty",
                        "attributePath": "password",
                        "detail": "must not be empty",
                        "invalidValue": ""
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the licenseType is invalid
        {
            "links": {},
            "error": {
                "reference": "f04a1a1e-0046-4b86-b9c3-da491d3343b5",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Deserialization error",
                        "constraint": "Must be one of [NAMED, CONCURRENT, BUILTIN].",
                        "attributePath": "licenseType",
                        "detail": "Cannot deserialize enum 'LicenseType' from value 'asd'. Possible values are [NAMED, CONCURRENT, BUILTIN].",
                        "invalidValue": "asd",
                        "possibleValues": [
                            "NAMED",
                            "CONCURRENT",
                            "BUILTIN"
                        ]
                    }
                ],
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to create users
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 403 (application/json)

        // when you can't assign Super Administrator role because you don't have the Super Administrator role when you create users
        {
        "links": {},
            "error": {
                "detail": "It's not possible to make these changes. You need Super Administrator role to create or edit a user with this role.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 409 (application/json)

        // when the same user was created more than once
        {
        "links": {},
            "error": {
                "reference": "a159c153-e99b-4d49-9987-ca457670ef86",
                "detail": "Licensing error (Invalid user id (message ID #2): A user with the name 'fred' already exists. Please provide a different user name or spell the user name appropriately.)",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

+ Response 500 (application/json)

        // when there's an unspecified error
        {
            "links": {},
            "error": {
                "reference": "4f356c86-aac1-4cae-8d78-518aea6cebe0",
                "detail": "An unspecific server error occurred. Details may be found in the Acrolinx log files.",
                "type": "server",
                "title": "Unspecific server error",
                "status": 500
            }
        }

+ Request Create a user with specified custom field values (application/json)

    This request will create a new user with specified custom field values.

    + Attributes (CreateUser)

    + Body

            {
                "username": "fred",
                "fullName": "Fred Freelancer",
                "password": "P@ssW0rd12345!",
                "customFields": [
                    {
                        "key": "Department",
                        "value": "Example Department"
                    }
                ]
            }

+ Response 201 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "Fred Freelancer",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                            "name": "Term Contributor"
                        },
                        {
                            "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                            "name": "Term Browser Administrator"
                        }
                    ],
                    "idpUser": false,
                    "staffUser": false,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        }
                    ]
                }
            }

+ Response 400 (application/json)

        // when the request format is invalid
        {
            "links": {},
            "error": {
                "detail": "Unexpected character ....",
                "type": "client",
                "title": "Could not parse request body.",
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2021.05
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Size",
                        "attributePath": "password",
                        "detail": "size must be between 1 and 128",
                        "invalidValue": "simple"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "attributePath": "password",
                        "detail": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "invalidValue": "not a secure password"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password is omitted starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotEmpty",
                        "attributePath": "password",
                        "detail": "must not be empty",
                        "invalidValue": ""
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "attributePath": "password",
                        "detail": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "invalidValue": "not a secure password"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password is omitted starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotEmpty",
                        "attributePath": "password",
                        "detail": "must not be empty",
                        "invalidValue": ""
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the licenseType is invalid
        {
            "links": {},
            "error": {
                "reference": "f04a1a1e-0046-4b86-b9c3-da491d3343b5",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Deserialization error",
                        "constraint": "Must be one of [NAMED, CONCURRENT, BUILTIN].",
                        "attributePath": "licenseType",
                        "detail": "Cannot deserialize enum 'LicenseType' from value 'asd'. Possible values are [NAMED, CONCURRENT, BUILTIN].",
                        "invalidValue": "asd",
                        "possibleValues": [
                            "NAMED",
                            "CONCURRENT",
                            "BUILTIN"
                        ]
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the provided custom field value is not in the list of possible values
        {
            "links": {},
            "error": {
                "detail": "Cannot set custom field \"Department\" as its value is not one of \"Example Department\".",
                "type": "customFieldsIncorrect",
                "title": "Custom field values are incorrect",
                "validationDetails": [
                    {
                        "title": "Invalid custom field value",
                        "constraint": "Must be one of \"Example Department\".",
                        "attributePath": "customFields.Department",
                        "detail": "Cannot set custom field \"Department\" as its value is not one of \"Example Department\".",
                        "invalidValue": "My Department",
                        "possibleValues": [
                            "Example Department"
                        ],
                        "type": "InvalidValue"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the provided custom field does not exists
        {
            "links": {},
            "error": {
                "detail": "Cannot set custom field \"T-Shirt size\" as its value is not one of \"Department\".",
                "type": "customFieldsIncorrect",
                "title": "Custom field values are incorrect",
                "validationDetails": [
                    {
                        "title": "Invalid custom field name",
                        "constraint": "Must be one of \"Department\".",
                        "attributePath": "customFields.T-Shirt size",
                        "detail": "Cannot set custom field \"T-Shirt size\" as its value is not one of \"Department\".",
                        "invalidValue": "T-Shirt size",
                        "possibleValues": [
                            "Department"
                        ],
                        "type": "InvalidField"
                    }
                ],
                "status": 400
            }
        }


+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to create users
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 409 (application/json)

        // when the same user was created more than once
        {
        "links": {},
            "error": {
                "reference": "a159c153-e99b-4d49-9987-ca457670ef86",
                "detail": "Licensing error (Invalid user id (message ID #2): A user with the name 'fred' already exists. Please provide a different user name or spell the user name appropriately.)",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

+ Response 500 (application/json)

        // when there's an unspecified error
        {
            "links": {},
            "error": {
                "reference": "4f356c86-aac1-4cae-8d78-518aea6cebe0",
                "detail": "An unspecific server error occurred. Details may be found in the Acrolinx log files.",
                "type": "server",
                "title": "Unspecific server error",
                "status": 500
            }
        }



### Update a user [PUT /api/v1/user/{id}]

+ Parameters
    + id: `eb323701-839f-4998-b56e-3e20c70259c5` (string, required) - UUID of the user, unique identifier

+ Request Update fullName attribute (application/json)

    You can update the fullName attribute for a user.

    In this example, only the `fullName` attribute will change for the user `fred`. This was identified in the database by its *id*.

    **Note:**
    - You can delete the `fullName` by changing the attribute to empty.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)
        + fullName (string, required)

    + Body

            {
                "fullName": "New Full Name"
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "New Full Name",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "uqlyxi3cdxrdqn7bzwdfffyvzr",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                            "name": "Term Contributor"
                        },
                        {
                            "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                            "name": "Term Browser Administrator"
                        }
                    ],
                    "idpUser": false,
                    "staffUser": false,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        }
                    ]
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to update users
        {
            "links": {},
                "error": {
                    "detail": "The user doesn't have the privileges required to perform the operation.",
                    "type": "insufficientPrivileges",
                    "title": "Insufficient privileges",
                    "status": 403
            }
        }

+ Response 404 (application/json)

        // when the user couldn't be identified by its *id* in the database
        {
        "links": {},
            "error": {
                "reference": "57380cf5-7f4d-481f-9490-375c950afe9d",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

+ Request Update roles (application/json)

    You can update a user's role.

    In this example, only the `roles` attribute will change for the user `fred`. This was identified in the database by its *id*. Each user needs at least one assigned role. This doesn't apply to built-in users. You can only assign the Super Administrator role if you have the Super Administrator role. If you add a role that doesn't exist, the call will fail and the error message will show the unknown roles that were referenced.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)
        + roles (array[Role], required)

    + Body

            {
                "roles": [{"id": "8c66c4e2-174a-4f77-b8d4-71bfa9ca4d2e"}]
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "New Full Name",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                            "name": "Term Contributor"
                        },
                        {
                            "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                            "name": "Term Browser Administrator"
                        }
                    ],
                    "idpUser": false,
                    "staffUser": false,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        }
                    ]
                }
            }

+ Response 400 (application/json)

        // when the roles array is empty
        {
            "links": {},
            "error": {
                "reference": "aecbef3d-d1a5-4d69-8d6c-3639f3d944b1",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotEmpty",
                        "attributePath": "roles",
                        "detail": "must not be empty",
                        "invalidValue": "[]"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when one or more of the roles that are specified that do not exist
        {
            "links": {},
            "error": {
                "reference": "57380cf5-7f4d-481f-9490-375c950afe9d",
                "detail": "The following role(s) could not be found when trying to assign them to user with ID eb323701-839f-4998-b56e-3e20c70259c5: [Role One], [Role Two]",
                "type": "entityToAssociateNotFound",
                "title": "The requested role(s) could not be found.",
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the user has their roles managed by their identity provider
        {
            "links": {},
            "error": {
                "reference": "57380cf5-7f4d-481f-9490-375c950afe9d",
                "detail": "You cannot update this users roles, because they are managed by the user's IDP"
                "type": "validation",
                "title": "Cannot update roles"
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to grant a role
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

        // when you can't assign Super Administrator role because you don't have the Super Administrator role when you edit users
        {
        "links": {},
            "error": {
                "detail": "It's not possible to make these changes. You need Super Administrator role to create or edit a user with this role.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 409 (application/json)

        // when you try to update a built-in user
        {
        "links": {},
            "error": {
                "detail": "Not possible to update built-in user",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

+ Request Set a custom field (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)
        + customFields (array[CustomField])

    + Body

            {
                "customFields": [
                    {
                        "key": "Test Field",
                        "value": "This is a string of text"
                    },
                    {
                        "key": "Department",
                        "value": "Example Department"
                    }
                ]
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "Fred Freelancer",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "uqlyxi3cdxrdqn7bzwdfffyvzr",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                            "name": "Term Contributor"
                        },
                        {
                            "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                            "name": "Term Browser Administrator"
                        }
                    ],
                    "idpUser": false,
                    "staffUser": false,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        },
                        {
                            "key": "Test Field",
                            "displayName": "Test Field",
                            "inputType": "optional",
                            "type": "text",
                            "value": "This is a string of text",
                            "possibleValues": [
                                "Item"
                            ]
                        }
                    ]
                }
            }

+ Request Clear a custom field (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)
        + customFields (array[CustomField])

    + Body

            {
                "customFields": [
                    {
                        "key": "Test Field",
                        "value": ""
                    },
                    {
                        "key": "Department",
                        "value": ""
                    }
                ]
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "Fred Freelancer",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "uqlyxi3cdxrdqn7bzwdfffyvzr",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                            "name": "Term Contributor"
                        },
                        {
                            "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                            "name": "Term Browser Administrator"
                        }
                    ],
                    "idpUser": false,
                    "staffUser": false,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        },
                        {
                            "key": "Test Field",
                            "displayName": "Test Field",
                            "inputType": "optional",
                            "type": "text",
                            "value": "This is a string of text",
                            "possibleValues": [
                                "Item"
                            ]
                        }
                    ]
                }
            }

+ Response 400 (application/json)

        // when any of the updated fields are invalid, you'll see a detailed error message
        {
            "links": {},
            "error": {
                "detail": "Cannot set custom field \"Department\" as its value is not one of \"Example Department\".",
                "type": "customFieldsIncorrect",
                "title": "Custom field values are incorrect",
                "validationDetails": [
                    {
                        "title": "Invalid custom field value",
                        "constraint": "Must be one of \"Example Department\".",
                        "attributePath": "customFields.Department",
                        "detail": "Cannot set custom field \"Department\" as its value is not one of \"Example Department\".",
                        "invalidValue": "This is not valid",
                        "possibleValues": [
                            "Example Department"
                        ],
                        "type": "InvalidValue"
                    }
                ],
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }
+ Response 403 (application/json)

        // when you don't have the privilege to update custom fields
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when a role wasn't found in the database based on its *id*
        {
        "links": {},
            "error": {
                "reference": "57380cf5-7f4d-481f-9490-375c950afe9d",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

+ Request Update password attribute (application/json)

    You can update the password attribute for a user.

    In this example, only the `password` attribute will change for the user `fred`. This was identified in the database by its *id*.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)
        + fullName (string, required)

    + Body

            {
                "password": "New_Secure_P@ssW0rd"
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": {
                    "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                    "username": "fred",
                    "fullName": "New Full Name",
                    "createdOn": "2021-04-15T15:00:26.495Z",
                    "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                    "licenseType": "named",
                    "licenseStatus": "inactive",
                    "activeTokenId": "uqlyxi3cdxrdqn7bzwdfffyvzr",
                    "checkingFrequency": "infrequent",
                    "properties" : {
                        "customkey": "customvalue",
                    },
                    "roles": [
                        {
                            "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                            "name": "Term Contributor"
                        },
                        {
                            "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                            "name": "Term Browser Administrator"
                        }
                    ],
                    "idpUser": false,
                    "staffUser": false,
                    "rolesSetByIdp": false,
                    "customFields": [
                        {
                            "key": "Department",
                            "displayName": "Department",
                            "inputType": "optional",
                            "type": "list",
                            "value": "Example Department",
                            "possibleValues": [
                                "Example Department"
                            ]
                        }
                    ]
                }
            }
+ Response 400 (application/json)

        // when the password doesn't meet the strictness requirements starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "attributePath": "password",
                        "detail": "Password must be composed of printable ASCII characters and contain at least 1 lower-case, 1 upper-case letter, 1 digit, one symbol and must be between 10 to 64 characters in length",
                        "invalidValue": "not a secure password"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when the password is omitted starting from v2022.02
        {
            "links": {},
            "error": {
                "reference": "30c5db1e-fabd-4815-890a-a55416e6c3be",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotEmpty",
                        "attributePath": "password",
                        "detail": "must not be empty",
                        "invalidValue": ""
                    }
                ],
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }
+ Response 403 (application/json)

        // when you don't have the privilege to update custom fields
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when a role wasn't found in the database based on its *id*
        {
        "links": {},
            "error": {
                "reference": "57380cf5-7f4d-481f-9490-375c950afe9d",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

### Delete a user [DELETE /api/v1/user/{id}]

This method deletes a specified user based on its *id*.

**Note:** You can only successfully delete a user under the following conditions:
- The user isn't a preconfigured, built-in user such as "admin", "termcontribution", or "analyticsReadOnlyUser".

To read more about managing users and built-in users, see [User Management](https://support.acrolinx.com/hc/en-us/sections/10210965582994-User-Management) in the Acrolinx documentation.

+ Parameters
    + id: `eb323701-839f-4998-b56e-3e20c70259c5` (string, required) - UUID of the user, unique identifier

+ Request Delete user by id

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 204

+ Response 400 (application/json)

        // when the request is invalid because of a typo, for example
        {
            "links": {},
            "error": {
                "reference": "eb323701-839f-4998-b56e-3e20c70259c5",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Bad Request",
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to delete a user
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the user wasn't found in the database based on its *id*
        {
        "links": {},
            "error": {
                "reference": "e49d3cd5-330a-408d-84a1-e9ecf20677bf",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

+ Response 409 (application/json)

        // when you can't delete a user
        {
            "links": {},
            "error": {
                "reference": "e9c4227c-e75b-4576-93e4-f5b4fec65d3b",
                "detail": "Built-in user \"termcontribution (termcontribution) \" cannot be deleted",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }


## Missing required user custom fields [/api/v1/user/custom-fields-missing]

Query users who don't have required custom fields.

**What's a missing required custom field?** The User API returns your user-related custom fields in the `customFields[]` array. If a custom field is required (marked with `"inputType": "required"`) and is missing a value (`"value": ""`), the field is considered to be missing.

**Note:**
- You need the `UserAndRoles.editUser` privilege.

### Count users [HEAD /api/v1/user/custom-fields-missing]

Returns the total number of users who are missing one or more required user custom fields.

**Note:**
- The response has no content.
- The user count appears in the header `X-Acrolinx-Total`.
- The header value is a numeral.
- It returns a 0 (zero) when all required custom fields are present.

+ Request

    Query the number of users who are missing information in one or more required user custom fields.

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 204

    + Headers

            X-Acrolinx-Total: 5

+ Response 401 (application/json)

+ Response 403 (application/json)

### Get users [GET /api/v1/user/custom-fields-missing{?page,per_page}]

Returns a list of users who are missing one or more required user custom fields.

**Note:** Similar to the User Resource > Get All Users request, it supports pagination. [See more details there](### Get all users).

+ Parameters

    + page: `5` (number, optional) - Optional query parameter for pagination
    + per_page: `20` (number, optional) - Optional query parameter for sizing a page

+ Request

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (User)

    + Body

            {
                "links": {},
                "data": [
                    {
                        "id": "eb323701-839f-4998-b56e-3e20c70259c5",
                        "username": "fred",
                        "fullName": "Fred Freelancer",
                        "createdOn": "2021-04-15T15:00:26.495Z",
                        "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                        "licenseType": "named",
                        "licenseStatus": "inactive",
                        "activeTokenId": "",
                        "checkingFrequency": "infrequent",
                        "properties" : {
                            "customkey": "customvalue",
                        },
                        "roles": [
                            {
                                "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                                "name": "Author"
                            }
                        ],
                        "idpUser": false,
                        "staffUser": false,
                        "rolesSetByIdp": false,
                        "customFields": [
                            {
                                "key": "Department",
                                "displayName": "Department",
                                "inputType": "optional",
                                "type": "list",
                                "value": "Example Department",
                                "possibleValues": [
                                    "Example Department"
                                ]
                            },
                            {
                            // Note that the value is empty ("") and the inputType is "required", so it's missing!
                                "key": "Employee number",
                                "displayName": "Employee number",
                                "inputType": "required",
                                "type": "text",
                                "value": "",
                                "possibleValues": []
                            }
                        ]
                    },
                    {
                        "id": "fd3eaa89-a6b7-463a-ba12-b7ded410bda0",
                        "username": "franz",
                        "fullName": "Franz Hubendobler",
                        "createdOn": "2021-02-23T17:24:01.131Z",
                        "lastIntegrationAccess": "1970-01-01T00:00:00Z",
                        "licenseType": "builtin",
                        "licenseStatus": "active",
                        "activeTokenId": "uqlyxi3cdxrdqn7bzwdfffyvzr",
                        "checkingFrequency": "infrequent",
                        "properties" : {
                            "customkey": "customvalue",
                        },
                        "roles": [
                            {
                                "id": "898a7c32-2c39-4cde-becb-16f22243e9b8",
                                "name": "Analytics Read-Only User"
                            }
                        ],
                        "idpUser": false,
                        "staffUser": false,
                        "rolesSetByIdp": false,
                        "customFields": [
                            {
                                "key": "Department",
                                "displayName": "Department",
                                "inputType": "optional",
                                "type": "list",
                                "value": "Example Department",
                                "possibleValues": [
                                    "Example Department"
                                ]
                            },
                            {
                            // Note that the value is empty ("") and the inputType is "required", so it's missing!
                                "key": "Employee number",
                                "displayName": "Employee number",
                                "inputType": "required",
                                "type": "text",
                                "value": "",
                                "possibleValues": []
                            }
                        ]
                    }
                ]
            }

+ Response 400 (appplication/json)

        // when the page parameter has an invalid value such as 0 or negative number
        {
            "links": {},
            "error": {
                "reference": "b2045b7f-1dce-49e7-880a-93874f427554",
                "detail": "Invalid page request attribute, it must be greater than zero",
                "type": "client",
                "title": "Bad Request",
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have sufficent privileges
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the page parameter has a non-numeric value, which is invalid
        {
            "links": {},
            "error": {
                "reference": "f1926760-f2e7-4af7-a3a6-f274bcb9a00f",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

## User-generated API tokens [/api/v1/user/{id}/tokens]

You can generate long-lived API tokens for programmatic access to Acrolinx APIs.

Acrolinx protects its APIs with self-contained access tokens. These access tokens let you authorize yourself as a user. API tokens have different characteristics than the access tokens that Acrolinx issues when you use the sign-in endpoint.

Don't forget to check out the *Introduction > Authentication and Authorization* section in this API documentation.

Note that you can only have one API token at a time.
* When you create a new API token, your previous API token becomes invalid.

**Warning:** Follow these security guidelines when you work with API tokens:
+ Store your API token securely and never share it with others.
+ Don't hardcode your API token in any custom code that interacts with the Acrolinx APIs.

**Note:** To learn more about creating API tokens, read [Create an API Token](https://support.acrolinx.com/hc/en-us/articles/10306041244818-Create-an-API-Token) in the Acrolinx documentation.

### Create an API token (Self)  [POST /api/v1/user/self/tokens]

Use this method to create an API token for the current user.

**Note:** You don't need extra privileges or roles to create a new API token associated with the user authorized in the request.

**Note:** This endpoint lets users use Basic authentication to avoid reusing an existing API token.

+ Request Create an API token using Basic authentication

    To authenticate using Basic authentication, provide your username and password in the `X-Acrolinx-Auth` request header in the format `Basic username:password`.

    * **Important:**
        * This request needs to have the prefix `Basic`.
        * Your credentials (`username:password`) must be base64 encoded.

    + Headers

            X-Acrolinx-Auth: Basic dGVzdDp0ZXN0

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (UserApiTokenCreateResponse)

    + Body

            {
                "links": {},
                "data": {
                    "type": "api",
                    "issuedAt": "2021-04-23T07:54:07Z",
                    "expiresAt": "2025-04-22T07:54:07Z",
                    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXJtY29udHJpYnV0aW9uIiwiYXVkIjoiYWNy..."
                }
            }

+ Response 401 (application/json)

        // when the credentails provided are missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Request Create an API token using an existing API token

    + Headers

            X-Acrolinx-Auth: // here you will find the existing API token

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (UserApiTokenCreateResponse)

    + Body

            {
                "links": {},
                "data": {
                    "type": "api",
                    "issuedAt": "2021-04-23T07:54:07Z",
                    "expiresAt": "2025-04-22T07:54:07Z",
                    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXJtY29udHJpYnV0aW9uIiwiYXVkIjoiYWNy..."
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

### Create an API token for users [POST /api/v1/user/{id}/tokens]

Use this method to create an API token for users based on their *id*.

Typical use cases for this API:
1. Create an API token for personal use
    - 1.1. Use the *Current user* request to get your own unique identifier *id*.
    - 1.2. Enter your *id* as a parameter.
    - 1.3. Start using the issued API token.
2. Create an API token for someone else
    - 2.1. Use the *Get users* request to get the unique identifier *id* for another user.
    - 2.2. Enter the other user's *id* as a parameter.
    - 2.3. Give the API token to the user securely.

**Note:** You can only create an API token if you have the appropriate privileges:
* To create an API token for yourself, you need to be authorized with a valid access token.
* To create an API token for someone else, you need the privilege `UserAndRoles.setApiTokensForOthers` and you need to be authorized with a valid access token.

**Alternative use case:** Create an API token to impersonate a user

    Sometimes an admin might want to impersonate a user to help troubleshoot.
    If a user comes across a bug, for example, an admin may want to impersonate the user to try and duplicate the problem.

+ Parameters
    + id: `eb323701-839f-4998-b56e-3e20c70259c5` (string, required) - UUID of the user, unique identifier

+ Request Create an API token for someone by user id

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (UserApiTokenCreateResponse)

    + Body

            {
                "links": {},
                "data": {
                    "type": "api",
                    "issuedAt": "2021-04-23T07:54:07Z",
                    "expiresAt": "2025-04-22T07:54:07Z",
                    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXJtY29udHJpYnV0aW9uIiwiYXVkIjoiYWNyb2xpbngiLCJuYmYiOjE2MTkwNzgwNDcsImlzcyI6ImFjcm9saW54OjAwMDBmZmZmZmZmZjAwMDAiLCJleHAiOjE3NDUzMDg0NDcsInRva2VuVHlwZSI6ImFwaSIsImlhdCI6MTYxOTE2NDQ0NywianRpIjoid3lvaXZoenl3Y3dwN3B4ejc2a29xN2F5NDQifQ.hRa2kHPl7EJ6xm115UOmu4QuppFoST7E626ceIsPeCI"
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when the user can't create an API token for others ("UserAndRoles.setApiTokensForOthers")
        {
            "links": {},
            "error": {
                "reference": "64311fe7-2a7e-4e3b-849e-4e9ff8651400",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 403 (application/json)

        // when the creator or receiver of the token is the built-in `admin`
        {
            "links": {},
            "error": {
                "reference": "64311fe7-2a7e-4e3b-849e-4e9ff8651400",
                "detail": "The built-in user `admin` mustn\'\'t create or retrieve any API tokens.",
                "type": "insufficientPrivileges",
                "title": "Can't Create API Token For `admin`",
                "status": 403
            }
        }

+ Response 403 (application/json)

        // when the user tries to create a token for another user with more elevated roles
        {
            "links": {},
            "error": {
                "reference": "64311fe7-2a7e-4e3b-849e-4e9ff8651400",
                "detail": "Operating user attempted to assign more elevated privileges than their own. This isn't allowed.",
                "type": "insufficientPrivileges",
                "title": "Privilege Escalation (Insufficient Privileges)",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the user wasn't found in the database based on its *id*

## Random passwords [/api/v1/user/random-passwords]

You can generate random passwords that meet the Acrolinx password policy.
This API is convenient when you want to create new users.

### Get a randomly generated compliant password [GET /api/v1/user/random-passwords]

**Password Requirements**

A password needs to meet the following requirements:

- Composed of ASCII printable characters
- Includes at least 1 lowercase letter
- Includes at least 1 uppercase letter
- Includes at least 1 digit
- Includes at least 1 special character
- At least 10 characters long
- No more than 64 characters long

**Note:**
- You need the `UserAndRoles.editUser` privilege.
- The randomly generated password isn't saved anywhere.
- The HTTP requests aren't cached.
- The randomly generated passwords are always 20 characters long.

+ Request Get a random password from the API

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Headers

            Cache-Control: private, no-cache, no-transform, must-revalidate, max-age=0
            Pragma: no-Cache
            Expires: Thu, 01 Jan 1970 00:00:00 GMT

    + Attributes (object)
        + links (object)
        + data (RandomPassword)

    + Body

            {
                "links": {},
                "data": {
                    "value": "#n(Y2Ne|=ODfEV @,y8I"
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when the user doesn't have the privilege to modify users ("UserAndRoles.editUser")
        {
            "links": {},
            "error": {
                "reference": "64311fe7-2a7e-4e3b-849e-4e9ff8651400",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 503 (application/json)

        // when the random password generator takes too long to generate an acceptable password
        {
            "links": {},
            "error": {
                "detail": "the service was unable to process your request at this time, please try again",
                "type": "temporaryUnavailable",
                "title": "Temporarily unable to process the request",
                "status": 503
            }
        }

## User commands [/api/v1/user/{id}/_{command}]

The APIs in this group follow the API design command style.

Use these administrative commands to manage users in your Acrolinx instance. The commands can do more than simply (re)send the new state of a single resource.

**Note:** You can apply these requests multiple times without changing the result (idempotent).

### Release an active named user license [PUT /api/v1/user/{id}/_release]

This method uses the *id* to release an active license consumed by a user.

**Note:**
- You can only release users with the `named` license type.
- If you release the license of a user who isn't consuming a license, you won't see an error.
- To release licenses, you need the `UserAndRoles.deleteSessions` privilege.

**Result:** User's `licenseStatus` changed from `active` to `inactive`.

+ Parameters
    + id: `eb323701-839f-4998-b56e-3e20c70259c5` (string, required) - UUID of the user, unique identifier

+ Request Release an Active Named User License by user id

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 204

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to release other users' licenses ("UserAndRoles.deleteSessions")
        {
            "links": {},
            "error": {
                "reference": "64311fe7-2a7e-4e3b-849e-4e9ff8651400",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the user wasn't found in the database by its *id*
        {
        "links": {},
            "error": {
                "reference": "e49d3cd5-330a-408d-84a1-e9ecf20677bf",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

### Request user information update  [PUT /api/v1/user/{id}/_request_cf_update]

The user specified by the *id* in this request will be asked to update their user information.

**Note:**
- The next time the user signs in, they'll need to re-enter their user information in a form.
- If you repeat the request for the same user UUID, you won't be notified that you already submitted a request.
- To request a user information update, you need the `UserAndRoles.editUser` privilege.

+ Parameters
    + id: `eb323701-839f-4998-b56e-3e20c70259c5` (string, required) - UUID of the user, unique identifier

+ Request Ask one user to update their user information

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 204

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the neccessary privileges ("UserAndRoles.editUser")
        {
            "links": {},
            "error": {
                "reference": "64311fe7-2a7e-4e3b-849e-4e9ff8651400",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the user wasn't found in the database by its *id*
        {
        "links": {},
            "error": {
                "reference": "e49d3cd5-330a-408d-84a1-e9ecf20677bf",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

### Export a list of users [GET /api/v1/user/_export]

This API provides an easy way to export a concise user list in a text file.

The endpoint uses content negotiation to determine the format of the export. To specify the format you prefer, include the `Accept` header in your request. See the `Supported formats` section for more information about the formats that Acrolinx currently supports.

**Supported formats:**
+ `text/csv` (default, file extension is `.csv`)

**Note:** If you don't specify the format in the `Accept` header, the default will be used.

**Content Disposition:**

The API also returns the `Content-Disposition` response header to give information about the returned content.
With this information, browsers can recognize downloadable attachments that users can save locally.

Set the header parameters as follows:
+ `attachment` - Indicates that the content should be downloaded.
+ `filename="acrolinx_users_export_yyyyMMdd_HHmmss.{fileExt}"` - Most browsers present a "Save as" dialog for attachments. This will be prefilled with the value of the filename parameter.

+ Request Export a list of users in CSV format

    This lets you export a list of users and their data as a CSV file that looks like a spreadsheet but has a `.csv` extension.
    Each line of the file is a user data record. Each record consists of one or more user fields and the actual value, separated by column delimiters.
    The CSV file works with most spreadsheet programs, such as Microsoft Excel or Google Sheets.

    The file contains the following user fields (in the specified order):
    + **user_id**: The user's unique identifier (string, UUID).
    + **Username**: The user's username, which can be used for sign in and user identification.
    + **Full name**: The full name of the user.
    + **Roles**: A list of assigned roles.
    + **Created on**: Indicates when the user was created.
    + **Last integration access**: Indicates when the user last accessed an integration. If the user hasn't accessed an integration, the default value is `Never`.
    + **Checking frequency**: Gives a rough idea of the pattern of checking frequency across a user's lifetime in days. Its value can be [ "frequent", "infrequent', "regular" ].
    + **License type**: Indicates the type of license. Its value can be ["named", "concurrent", "builtin"].
    + **{Custom Field name}**: Users can have multiple (0...N) custom fields that are also attached to the schema.
        + For custom fields, the column name is mapped from the custom field's name (specified when you create it). The column will be dynamically added to the end of the sheet.

    **Notes about the CSV file and data formatting:**
    + Column headers are also written in the first row of the file.
    + Fields are separated by a semicolon `;` (as column delimiter).
    + Date and time values are exported in `UTC`, for example `2021-05-12T15:40:00.876Z`.
        + When there's no stored value for a given Date time type field, the cell should contain `Never` or an empty value.
    + Values of a list type field are separated by a colon `:` (as the "in-cell" delimiter).
    + Values that contain space characters are in double quotes in the file, for example, `user_id;Username;"Full Name";...`.

    + Headers

            Accept: text/csv
            X-Acrolinx-Auth: your_access_token

+ Response 200 (text/csv)

    + Headers

            Content-Disposition: attachment; filename="acrolinx_users_export_20210514_101248.csv"

    + Body

            user_id;Username;"Full Name";Roles;"Created On";"Last Integration Access";"Checking Frequency";"License Type";"License Status";Department
            "1ba8d14c-7697-4dbd-b370-3d22662e6fe0";termcontribution;"Term Contribution";"Term Contributor";"2021-05-12T15:40:00.876Z";Never;infrequent;builtin;inactive;"R&D"
            "f265a1b7-4fed-4ff3-b2d4-9dc6e29e268f";analyticsReadOnlyUser;"Analytics Read Only User";"Analytics Read-Only User";"2021-05-12T15:40:00.876Z";Never;infrequent;builtin;inactive;"Example Department"
            "4f86f443-e5e3-49c9-93da-cb1f89cd28c7";admin;Adminisztrator;"Super Administrator";"2021-05-12T15:40:00.866Z";Never;infrequent;builtin;inactive;IT
            "05aa0b12-a3b1-455f-9aa6-f48034c191ae";termapiaccess;"Term API Access (builtin)";"Terminology API Access";"2021-05-12T15:40:00.876Z";Never;infrequent;builtin;inactive;
            "394cdff2-bde8-41d2-85cd-34cd3bbca350";termtargetaccess;"Term Target Access (builtin)";"Term Browser User, Term Browser Administrator";"2021-05-12T15:40:00.876Z";Never;infrequent;builtin;inactive;

+ Response 401 (application/json)

        // when the access token in the request is missing or is invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to export users ("UsersAndRoles.editUser")
        {
            "links": {},
            "error": {
                "reference": "64311fe7-2a7e-4e3b-849e-4e9ff8651400",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Request Export users with an unsupported media type

    If you enter an unsupported media type in the `Accept` header, for example, `text/html`, the API will return the http status `406 - Not Acceptable`.

    + Headers

            Accept: text/html
            X-Acrolinx-Auth: your_access_token

+ Response 406

        {
            "links": {},
            "error": {
                "reference": "1baade57-4292-49c9-81b8-fdaa815123fb",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Acceptable",
                "status": 406
            }
        }

## User bulk operations [/api/v1/user/bulk]

Use these APIs to perform bulk operations. Bulk operations follow the multi-status request and response model.
In this model, the incoming bulk request includes a list of objects that need to be processed (as opposed to using the same API many times).
The response to the request is `207 Multi-Status`. The response includes a list of `results` for the objects that were processed successfully
and a list of `errors` for the objects that couldn't be processed.

**Note:** Each API has a limit for bulk requests. User creation is an atomic operation, but the bulk request is nontransactional.

### Create users in bulk [POST /api/v1/user/bulk]

Use this API to create a list of new users. All user objects follow the requirements and constraints
noted in the Create User API section.

**Note:** With each bulk request, you can create up to 100 users. The minimum is 1.

+ Request Create Users in Bulk (application/json)

    This request lets you create 5 new users by specifying some basic fields (`username`, `fullName`, `password`) in the request model.

    **Note:** Acrolinx will automatically assign a license type and role. These typically have the license type `named` and the role `Author`.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (BulkCreateUser)

    + Body

            [
                {
                    "username": "new.user.1",
                    "fullName": "New User 1",
                    "password": "P@ssW0rd12345!"
                },
                {
                    "username": "new.user.2",
                    "fullName": "New User 2",
                    "password": "P@ssW0rd12345!"
                },
                {
                    "username": "new.user.3",
                    "fullName": "New User 3",
                    "password": "P@ssW0rd12345!"
                },
                {
                    "username": "new.user.4",
                    "fullName": "New User 4",
                    "password": "P@ssW0rd12345!"
                },
                {
                    "username": "new.user.5",
                    "fullName": "New User 5",
                    "password": "P@ssW0rd12345!"
                }
            ]
+ Response 207 (application/json)

    + Attributes (BulkResultResponse)

    + Body

            // When all users were successfully created
            {
                "results": [
                    {
                        "status": 201,
                        "id": "c06de3b6-46c3-46d8-a136-afb6501f88e3",
                        "location": "http://tenant.acrolinx.cloud/api/v1/user/c06de3b6-46c3-46d8-a136-afb6501f88e3"
                    },
                    {
                        "status": 201,
                        "id": "3bd446b9-6371-4ecb-a4fb-ebeb01bae9e3",
                        "location": "http://tenant.acrolinx.cloud/api/v1/user/3bd446b9-6371-4ecb-a4fb-ebeb01bae9e3"
                    },
                    {
                        "status": 201,
                        "id": "4d8a94a8-55fe-4ee6-bf67-8f21a335e7da",
                        "location": "http://tenant.acrolinx.cloud/api/v1/user/4d8a94a8-55fe-4ee6-bf67-8f21a335e7da"
                    },
                    {
                        "status": 201,
                        "id": "76d79076-fbf7-4e02-89b5-a9c52d38b5e6",
                        "location": "http://tenant.acrolinx.cloud/api/v1/user/76d79076-fbf7-4e02-89b5-a9c52d38b5e6"
                    },
                    {
                        "status": 201,
                        "id": "a3b18412-4e61-4795-b5c0-4b2fc82f7995",
                        "location": "http://tenant.acrolinx.cloud/api/v1/user/a3b18412-4e61-4795-b5c0-4b2fc82f7995"
                    }
                ],
                "errors": []
            }


            // when 3 users were created successfully but 2 weren't
            {
                "results": [
                    {
                        "status": 201,
                        "id": "c06de3b6-46c3-46d8-a136-afb6501f88e3",
                        "location": "http://tenant.acrolinx.cloud/api/v1/user/c06de3b6-46c3-46d8-a136-afb6501f88e3"
                    },
                    {
                        "status": 201,
                        "id": "3bd446b9-6371-4ecb-a4fb-ebeb01bae9e3",
                        "location": "http://tenant.acrolinx.cloud/api/v1/user/3bd446b9-6371-4ecb-a4fb-ebeb01bae9e3"
                    },
                    {
                        "status": 201,
                        "id": "4d8a94a8-55fe-4ee6-bf67-8f21a335e7da",
                        "location": "http://tenant.acrolinx.cloud/api/v1/user/4d8a94a8-55fe-4ee6-bf67-8f21a335e7da"
                    }
                ],
                "errors": [
                    {
                        "status": 409,
                        "id": "test.user.4",
                        "type": "client",
                        "title": "Conflict",
                        "detail": "Licensing error (Invalid user id (message ID #2): A user with the name 'test.user.1' already exists. Please provide a different user name or spell the user name appropriately.)",
                        "reference": "68327a0f-db3e-459c-91f9-5a3da691a1d1"
                    },
                    {
                        "status": 409,
                        "id": "test.user.5",
                        "type": "client",
                        "title": "Conflict",
                        "detail": "Licensing error (Invalid user id (message ID #2): A user with the name 'test.user.2' already exists. Please provide a different user name or spell the user name appropriately.)",
                        "reference": "4be034f9-c8f3-4465-9117-cde7c1f075ca"
                    }
                ]
            }

+ Response 400 (application/json)

        // when a bulk request is sent with an empty list
        {
            "links": {},
            "error": {
                "reference": "88892611-7955-4a8f-9f5f-71b99b31bdca",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Size",
                        "detail": "size must be between 1 and 100",
                        "invalidValue": "[]"
                    }
                ],
                "status": 400
            }
        }

        // when a bulk request exceeds the maximum valid limit
        {
            "links": {},
            "error": {
                "reference": "367fedac-e5bb-4229-9405-3fcc425bf1f5",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Size",
                        "detail": "size must be between 1 and 100",
                        "invalidValue": "[username=test.user.1, username=test.user.2, ... username=test.user.100, username=test.user.101]"
                    }
                ],
                "status": 400
            }
        }

        // when a bulk request includes validation errors such as an empty password
        {
            "links": {},
            "error": {
                "reference": "241a2429-0f53-49a6-a6af-72aaaf41ad36",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotEmpty",
                        "attributePath": "password",
                        "detail": "must not be empty",
                        "invalidValue": ""
                    }
                ],
                "status": 400
            }
        }

        // when a bulk request is sent without a payload body
        {
            "links": {},
            "error": {
                "reference": "82b2e14b-95f8-4789-8ee8-3822c2297a9c",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotNull",
                        "detail": "must not be null",
                        "invalidValue": null
                    }
                ],
                "status": 400
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to create users
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 500 (application/json)

        // when there's an unspecified error
        {
            "links": {},
            "error": {
                "reference": "2f17395a-770f-439e-b2b4-65c6c03717db",
                "detail": "An unspecific server error occurred. Details may be found in the Acrolinx log files.",
                "type": "server",
                "title": "Unspecific server error",
                "status": 500
            }
        }


### Request user information update in bulk  [PUT /api/v1/user/bulk/_request_cf_update]

This API is the bulk operation of "Request User Information Update" from the "User Commands" group.
It lets you ask multiple users to update their user information.

**Note:** Currently, there's no limit on the number of users that you can request to update their information.

+ Request Ask multiple users to update their user information (application/json)

  + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)

    + Body

            [
                "1f17395a-770f-439e-b2b4-65c6c03717db",
                "2f17395a-770f-439e-b2b4-65c6c03717db",
                "3f17395a-770f-439e-b2b4-65c6c03717db",
            ]

+ Response 207 (application/json)

    + Attributes (BulkResultResponse)

    + Body

            {
                "results": [
                    {
                        "status": 204,
                        "id": "1f17395a-770f-439e-b2b4-65c6c03717db",
                    },
                    {
                        "status": 204,
                        "id": "2f17395a-770f-439e-b2b4-65c6c03717db",
                    },
                    {
                        "status": 204,
                        "id": "3f17395a-770f-439e-b2b4-65c6c03717db",
                    }
                ],
                "errors": []
            }

+ Response 403 (application/json)

        // when you don't have the neccessary privileges ("UserAndRoles.editUser")
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 500 (application/json)

        // when there's an unspecified error
        {
            "links": {},
            "error": {
                "reference": "2f17395a-770f-439e-b2b4-65c6c03717db",
                "detail": "An unspecific server error occurred. Details may be found in the Acrolinx log files.",
                "type": "server",
                "title": "Unspecific server error",
                "status": 500
            }
        }

+ Request Error Example - If user ids in the request are invalid or unknown (application/json)

  + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)

    + Body

            [
                "f265a1b7-4fed-4ff3-b2d4-9dc6e29e268f",
                "no-user-with-this-id-for-sure",
                null
            ]

+ Response 207 (application/json)

    + Attributes (BulkResultResponse)

    + Body

            {
                 "results": [
                     {
                         "status": 204,
                         "id": "f265a1b7-4fed-4ff3-b2d4-9dc6e29e268f"
                     }
                 ],
                 "errors": [
                     {
                         "status": 400,
                         "id": null,
                         "type": "client",
                         "title": "Bad Request",
                         "detail": "The provided uuid is not a valid user id.",
                         "reference": "d18c9c62-faed-4753-b4f4-6a6d6e967d9e"
                     },
                     {
                         "status": 404,
                         "id": "no-user-with-this-id-for-sure",
                         "type": "client",
                         "title": "Not Found",
                         "detail": "User does not exist with the given id.",
                         "reference": "592577df-4526-4eea-a4bb-1628102a063c"
                     }
                 ]
             }

+ Response 403 (application/json)

        // when you don't have the neccessary privileges ("UserAndRoles.editUser")
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 500 (application/json)

        // when there's an unspecified error
        {
            "links": {},
            "error": {
                "reference": "2f17395a-770f-439e-b2b4-65c6c03717db",
                "detail": "An unspecific server error occurred. Details may be found in the Acrolinx log files.",
                "type": "server",
                "title": "Unspecific server error",
                "status": 500
            }
        }

### Delete users in bulk [DELETE /api/v1/user/bulk]

This API lets you delete a list of users. All user ids follow the requirements and constraints
noted in the "Delete User API" section.

**Note:** With each bulk request, you can delete up to 100 users. The minimum is 1.

+ Request Delete users in bulk (application/json)

    This request lets you delete 5 users by specifying user UUIDs in the request object.

    Example when all users were successfully deleted

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Body

            [
                "d6601a5b-c74e-4753-8d7a-4a7d15e71149",
                "d7b6d898-79b2-4a8b-9afd-760fdda9c921",
                "bb284474-e107-413e-9c15-d813ed7209e9",
                "c4eba54b-4cb6-4045-85f1-88e72fd9be6f",
                "b08309c7-87ee-4270-8d94-de5a916d24be"
            ]

+ Response 207 (application/json)

    + Attributes (BulkResultResponse)

    + Body

            {
                "results": [
                    {
                        "status": 204,
                        "id": "d6601a5b-c74e-4753-8d7a-4a7d15e71149"
                    },
                    {
                        "status": 204,
                        "id": "d7b6d898-79b2-4a8b-9afd-760fdda9c921"
                    },
                    {
                        "status": 204,
                        "id": "bb284474-e107-413e-9c15-d813ed7209e9"
                    },
                    {
                        "status": 204,
                        "id": "c4eba54b-4cb6-4045-85f1-88e72fd9be6f"
                    },
                    {
                        "status": 204,
                        "id": "b08309c7-87ee-4270-8d94-de5a916d24be"
                    }
                ],
                "errors": []
                }

+ Request Example with users that can't be deleted (application/json)

  + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)

    + Body

            [
                "d6601a5b-c74e-4753-8d7a-4a7d15e71149",
                "d7b6d898-79b2-4a8b-9afd-760fdda9c921",
                "bb284474-e107-413e-9c15-d813ed7209e9",
                "c4eba54b-4cb6-4045-85f1-88e72fd9be6f",
                "b08309c7-87ee-4270-8d94-de5a916d24be"
            ]

+ Response 207 (application/json)

    + Attributes (BulkResultResponse)

    + Body

            {
                "results": [
                    {
                        "status": 204,
                        "id": "d6601a5b-c74e-4753-8d7a-4a7d15e71149"
                    },
                    {
                        "status": 204,
                        "id": "d7b6d898-79b2-4a8b-9afd-760fdda9c921"
                    }
                ],
                "errors": [
                    {
                        "status": 409,
                        "id": "b08309c7-87ee-4270-8d94-de5a916d24be",
                        "type": "client",
                        "title": "Conflict",
                        "detail": "Cannot delete own account",
                        "reference": "06bc308c-c65d-45eb-a626-a9cc5908798c"
                    },
                    {
                        "status": 409,
                        "id": "d6601a5b-c74e-4753-8d7a-4a7d15e71149",
                        "type": "client",
                        "title": "Conflict",
                        "detail": "Built-in user \"admin (admin) \" cannot be deleted",
                        "reference": "b08309c7-87ee-4270-8d94-de5a916d24be"
                    },
                    {
                        "status": 404,
                        "id": "d7b6d898-79b2-4a8b-9afd-760fdda9c921",
                        "type": "client",
                        "title": "Not Found",
                        "detail": "An unspecific client error occurred.",
                        "reference": "c0c67650-4fd6-42a4-9300-1f9431274912"
                    }
                ]
            }

+ Response 400 (application/json)

        // when a bulk delete request is sent with an empty list
        {
            "links": {},
            "error": {
                "reference": "ea0ef815-435b-4311-8937-c32ece0c7cc4",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Size",
                        "detail": "size must be between 1 and 100",
                        "invalidValue": "[]"
                    }
                ],
                "status": 400
            }
        }

        // when a bulk delete request exceeds the maximum valid limit
        {
            "links": {},
            "error": {
                "reference": "a2616dcb-1009-47c6-a6cd-34fe71776dd5",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Size",
                        "detail": "size must be between 1 and 100",
                        "invalidValue": "[d6601a5b-c74e-4753-8d7a-4a7d15e71149, d7b6d898-79b2-4a8b-9afd-760fdda9c921, ...]"
                    }
                ],
                "status": 400
            }
        }

        // when a bulk request is sent without a payload body
        {
            "links": {},
            "error": {
                    "reference": "f36cbe4d-0ebb-44c1-9771-2555cb17f025",
                    "detail": "Check the request for invalid values or missing parameters.",
                    "type": "validation",
                    "title": "Invalid request attributes",
                    "validationDetails": [
                        {
                            "title": "Validation error",
                            "constraint": "NotNull",
                            "detail": "must not be null",
                            "invalidValue": null
                        }
                ],
                "status": 400
            }
        }

+ Request Example with invalid or unknown user ids in request (application/json)

  + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)

    + Body

            [
                "f265a1b7-4fed-4ff3-b2d4-9dc6e29e268f",
                "no-user-with-this-id-for-sure",
                null
            ]

+ Response 207 (application/json)

    + Attributes (BulkResultResponse)

    + Body

            {
                "results": [
                    {
                        "status": 204,
                        "id": "33b5b2e3-6870-4ecb-92f9-ac496a9ac2c3"
                    }
                ],
                "errors": [
                    {
                        "status": 404,
                        "id": "no-user-with-this-id-for-sure",
                        "type": "client",
                        "title": "Not Found",
                        "detail": "HTTP 404 Not Found",
                        "reference": "8aafe860-8fa7-4f5f-89c6-40dda1c444c4"
                    },
                    {
                        "status": 400,
                        "id": null,
                        "type": "client",
                        "title": "Bad Request",
                        "detail": "The provided uuid is not a valid user id.",
                        "reference": "cc3c4907-5fa2-40e9-988a-3623a5c358d7"
                    }
                ]
            }

+ Response 403 (application/json)

        // when you don't have the privilege to delete users
        {
        "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 500 (application/json)

        // when there's an unspecified error
        {
            "links": {},
            "error": {
                "reference": "2f17395a-770f-439e-b2b4-65c6c03717db",
                "detail": "An unspecific server error occurred. Details may be found in the Acrolinx log files.",
                "type": "server",
                "title": "Unspecific server error",
                "status": 500
            }
        }

# Group Custom fields API

Use the API to set and view user custom fields.

**Note:** You only need a valid access token for this request (no special privileges needed).

## Custom fields [/api/v1/custom-fields/user]

### Get custom fields [GET]

Shows a list of your user custom fields.

+ Request Get Custom Fields (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (array[CustomField], fixed-type)

    + Body

            {
                "links": {},
                "data": [
                    {
                        "key": "key1",
                        "displayName": "displayName1",
                        "inputType": "required",
                        "type": "list",
                        "possibleValues": [
                            "",
                            "possibleValue1",
                            "possibleValue2"
                        ]
                    },
                    {
                        "key": "key2",
                        "displayName": "displayName2",
                        "inputType": "optional",
                        "type": "text"
                    }
                ]
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

# Group Licenses API

The following set of APIs provides license information.

## Statistics [/api/v1/licenses/statistics]

### Get license statistics for users [GET]

Returns license statistics for the Acrolinx instance and shows the sum of license types `named` and `concurrent`.
Acrolinx checks the following conditions for all users to qualify them for inclusion in the calculation:

- Must be one of the following License Types `named` or `concurrent`
- For `named` license they must be active and satisfy the following:
    - Be activated for `Checking` session type
    - Must not be free of charge (built-in users)
- All other `named` licensed users are considered `inactive`
- All `concurrent` licensed users are `existing` if a license exists

**Note:** Built-in users such as `Admin`, `TermBrowser`, `TermTargetAccess`, `TermContribution`, `TermApiAccess`, and `AnalyticsReadOnlyUser`
are included in the license statistics along with all other users, but they’re subject to the conditions above.

The following table describes the statistics attributes:

| License type | Sum attribute | Description                   |
|:-------------|---------------|-------------------------------|
| `named`      | licensed      | Total number of licenses      |
| `named`      | active        | Total active licenses         |
| `named`      | inactive      | Total inactive licenses       |
| `named`      | available     | Total available licenses (`licensed` minus `active`) |
| `concurrent` | licensed      | Total number of licenses      |
| `concurrent` | existing      | Total number of licenses used |

**Note:**
- Must have `UserAndRoles.editUser` privileges to perform this request
- Concurrent license numbers may be seen (non-zero) if a license has been configured for both `named` and `concurrent` user limits

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data(LicenseStatistics)

    + Body

            {
                "links": {},
                "data": {
                    "named": {
                        "licensed": 150,
                        "active": 58,
                        "inactive": 23,
                        "available": 92
                    },
                    "concurrent": {
                        "licensed": 50,
                        "existing": 10
                    }
                }
            }

+ Response 401 (application/json)

        // When the access token is missing or is invalid in the request
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when there is insufficient privileges to fetch license statistics
        {
            "links": {},
            "error": {
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

# Group Role API

In the Role API, a role is an entity that has an id, a name and list of privileges, and information about whether this role is a default role.
You can use roles to group sets of privileges and assign them to different users.
Mark roles as default if you want to automatically assign at least one default role to all new users.

To read more about role-based access control in Acrolinx, see [User Roles](https://support.acrolinx.com/hc/en-us/articles/10210994316562-User-Roles).

**Note:** Before you start using the Role API, review the [authentication and authorization](https://acrolinxapi.docs.apiary.io/#introduction/authentication-and-authorization) requirements.

## Roles [/api/v1/roles/]

### Get all roles [GET]

Returns a list of all roles including the associated privileges.

+ Request

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (array[Role])

    + Body

            {
                "links": {},
                "data": [
                    {
                        "id": "fdcd7fc6-9715-42f8-a947-88812bc02b2a",
                        "name": "Term Browser User",
                        "privileges": [
                            "Terminology.read",
                            "Dashboard.logon",
                            "Termbrowser.logon"
                        ],
                        "default": false
                    },
                    {
                        "id": "8c66c4e2-174a-4f77-b8d4-71bfa9ca4d2e",
                        "name": "Author",
                        "privileges": [
                            "CheckingAndClients.checkingApplications",
                            "CheckingAndClients.downloadReports"
                        ],
                        "default": true
                    },
                    {
                        "id": "d66d4d00-3381-11e0-bc8e-0800200c9a66",
                        "name": "Term Contributor",
                        "privileges": [
                            "TermContribution.contributeTerms",
                            "TermContribution.commentTerms"
                        ],
                        "default": false
                    },
                    {
                        "id": "6a0ebe93-f735-4b08-b6f2-66f7ecc70190",
                        "name": "Term Browser Administrator",
                        "privileges": [
                            "Terminology.read",
                            "Dashboard.logon"
                        ],
                        "default": false
                    },
                    {
                        "id": "898a7c32-2c39-4cde-becb-16f22243e9b8",
                        "name": "Analytics Read-Only User",
                        "privileges": [
                            "Reporting.read",
                            "Dashboard.logon",
                            "CheckingAndClients.downloadReports"
                        ],
                        "default": false
                    },
                    {
                        "id": "bc5c91f3-fae1-49f7-8d60-d325077c6ef9",
                        "name": "Super Administrator",
                        "privileges": [
                            "UserAndRoles.read",
                            "Terminology.read",
                            "LinguisticConfiguration.configureAndDeployRules",
                            "LinguisticConfiguration.configureAndDeployReuse",
                            "CheckingAndClients.submitDictionaryEntry",
                            "CheckingAndClients.editPluginSegmentation",
                            "CheckingAndClients.terminologyApplications",
                            "TermContribution.contributeTerms",
                            "Reporting.administration",
                            "Servers.monitoring",
                            "Terminology.export",
                            "Terminology.edit",
                            "CheckingAndClients.checkingApplications",
                            "Terminology.undump",
                            "Servers.editNotification",
                            "CheckingAndClients.reuseApplications",
                            "CheckingAndClients.runTermHarvesting",
                            "TermContribution.commentTerms",
                            "Servers.downloadSupportPackage",
                            "LinguisticConfiguration.tuneResources",
                            "LinguisticConfiguration.reloadLanguageConfiguration",
                            "Terminology.customize",
                            "Reporting.create",
                            "LinguisticConfiguration.configureAndDeployTerminology",
                            "Servers.overlay",
                            "Terminology.dump",
                            "UserAndRoles.setApiTokensForOthers",
                            "Reporting.read",
                            "CheckingAndClients.editCheckingProfiles",
                            "Servers.readLicense",
                            "TermContribution.removeCommentTerms",
                            "ReuseManagement.edit",
                            "Dashboard.logon",
                            "UserAndRoles.editUser",
                            "Servers.editLicense",
                            "LinguisticConfiguration.editTargets",
                            "Termbrowser.logon",
                            "Servers.downloadLogs",
                            "UserAndRoles.deleteSessions",
                            "Terminology.import",
                            "Servers.capture",
                            "Servers.list",
                            "CheckingAndClients.downloadReports",
                            "Servers.restart",
                            "Terminology.termbrowserAdmin",
                            "ReuseManagement.read",
                            "Terminology.statusChange",
                            "CheckingAndClients.accessExtractedContent"
                        ],
                        "default": false
                    }
                ]
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to view users and roles ("UserAndRoles.read")
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

## Privileges [/api/v1/roles/privileges]

Privileges determine if a user can perform an action with the API or Acrolinx UI.

### Get all privileges [GET]

Returns a list of all supported privileges.

**Note:** In newer Acrolinx versions, we may introduce or remove privileges.
To find out which privileges come with your instance, submit this request and compare it to the example response.

+ Request

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (array[string])

    + Body

            {
                "links": {},
                "data": [
                    "CheckingAndClients.accessExtractedContent",
                    "CheckingAndClients.checkingApplications",
                    "CheckingAndClients.downloadReports",
                    "CheckingAndClients.editCheckingProfiles",
                    "CheckingAndClients.editPluginSegmentation",
                    "CheckingAndClients.reuseApplications",
                    "CheckingAndClients.runTermHarvesting",
                    "CheckingAndClients.submitDictionaryEntry",
                    "CheckingAndClients.terminologyApplications",
                    "Dashboard.logon",
                    "LinguisticConfiguration.configureAndDeployReuse",
                    "LinguisticConfiguration.configureAndDeployRules",
                    "LinguisticConfiguration.configureAndDeployTerminology",
                    "LinguisticConfiguration.editTargets",
                    "LinguisticConfiguration.reloadLanguageConfiguration",
                    "LinguisticConfiguration.tuneResources",
                    "Reporting.administration",
                    "Reporting.create",
                    "Reporting.read",
                    "ReuseManagement.edit",
                    "ReuseManagement.read",
                    "Servers.capture",
                    "Servers.downloadLogs",
                    "Servers.downloadSupportPackage",
                    "Servers.editLicense",
                    "Servers.editNotification",
                    "Servers.list",
                    "Servers.monitoring",
                    "Servers.overlay",
                    "Servers.readLicense",
                    "Servers.restart",
                    "TermContribution.commentTerms",
                    "TermContribution.contributeTerms",
                    "TermContribution.removeCommentTerms",
                    "Termbrowser.logon",
                    "Terminology.customize",
                    "Terminology.dump",
                    "Terminology.edit",
                    "Terminology.export",
                    "Terminology.import",
                    "Terminology.read",
                    "Terminology.statusChange",
                    "Terminology.termbrowserAdmin",
                    "Terminology.undump",
                    "UserAndRoles.deleteSessions",
                    "UserAndRoles.editUser",
                    "UserAndRoles.read",
                    "UserAndRoles.setApiTokensForOthers"
                ]
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to view users and roles ("UserAndRoles.read")
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

## Role [/api/v1/roles]

### Create roles [POST]

Adds new roles.

**Note:**
- The name needs to be unique and must be between 1 and 254 characters.
- The name should not contain semicolons.
- A role needs to have at least one privilege assigned.
- You must reference existing privileges.


+ Request Create a role (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (CreateOrUpdateRole)

    + Body

            {
                "name": "My new role",
                "privileges": [
                    "Dashboard.logon"
                ]
            }

+ Response 201 (application/json)

    + Attributes (object)
        + links (object)
        + data (Role)

    + Body

            {
                "links": {},
                "data": {
                    "id": "f608876c-a943-4ad2-82c1-e59df943ce41",
                    "name": "My new role",
                    "privileges": [
                        "Dashboard.logon"
                    ],
                    "default": false
                }
            }

+ Response 400 (application/json)

            // when an empty name was provided or the name provided is longer than 254 characters
            {
                "links": {},
                "error": {
                    "reference": "357a24b5-eb48-45c3-9527-9718506e6e10",
                    "detail": "Check the request for invalid values or missing parameters.",
                    "type": "validation",
                    "title": "Invalid request attributes",
                    "validationDetails": [
                        {
                            "title": "Validation error",
                            "constraint": "NotBlank",
                            "attributePath": "name",
                            "detail": "must not be blank",
                            "invalidValue": ""
                        },
                        {
                            "title": "Validation error",
                            "constraint": "Size",
                            "attributePath": "name",
                            "detail": "size must be between 1 and 254",
                            "invalidValue": ""
                        }
                    ],
                    "status": 400
                }
            }

+ Response 400 (application/json)

            // when empty privileges were provided
            {
                "links": {},
                "error": {
                    "reference": "55973236-1b1a-4d76-a62d-360f5d9a1e29",
                    "detail": "Check the request for invalid values or missing parameters.",
                    "type": "validation",
                    "title": "Invalid request attributes",
                    "validationDetails": [
                        {
                            "title": "Validation error",
                            "constraint": "NotEmpty",
                            "attributePath": "privileges",
                            "detail": "must not be empty",
                            "invalidValue": "[]"
                        }
                    ],
                    "status": 400
                }
            }

+ Response 400 (application/json)

            // when privilege keys that don't exist were referenced
            {
                "links": {},
                "error": {
                    "reference": "89f517a8-7d8e-4579-8879-5c6bbdd8fd5a",
                    "detail": "Check the request for invalid values or missing parameters.",
                    "type": "validation",
                    "title": "Invalid request attributes",
                    "validationDetails": [
                        {
                            "title": "Validation error",
                            "constraint": "Unknown privileges: My.privilege",
                            "attributePath": "privileges",
                            "detail": "Unknown privileges: My.privilege",
                            "invalidValue": "[My.privilege]"
                        }
                    ],
                    "status": 400
                }
            }

+ Response 400 (application/json)

            // when name contains semicolon
            {
                "links": {},
                "error": {
                    "reference": "569c236c-c981-4669-8ffc-4a000f127e9e",
                    "detail": "The client request failed because it contains missing parameters or invalid values.",
                    "type": "validation",
                    "title": "Invalid request attributes",
                    "validationDetails": [
                        {
                            "title": "Validation error",
                            "constraint": "Role name with semicolon is not allowed.",
                            "attributePath": "name",
                            "detail": "Role name with semicolon is not allowed.",
                            "invalidValue": ";"
                        }
                    ],
                    "status": 400
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to edit roles
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 409 (application/json)

        // when a role with the same name already exists
        {
            "links": {},
            "error": {
                "reference": "f3c9e0d7-1c86-4da3-916f-617d839d2da5",
                "detail": "A role with name 'My new role' already exists.",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

+ Request Create a default role (application/json)

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (CreateOrUpdateRole)

    + Body

            {
                "name": "This is Default",
                "privileges": [
                    "Dashboard.logon"
                ],
                "default": true
            }

+ Response 201 (application/json)

    + Attributes (object)
        + links (object)
        + data (Role)

    + Body

            {
                "links": {},
                "data": {
                    "id": "f608876c-a943-4ad2-82c1-e59df943ce42",
                    "name": "This is Default",
                    "privileges": [
                        "Dashboard.logon"
                    ],
                    "default": true
                }
            }

+ Response 400 (application/json)

            // when an empty name was provided or the name provided is longer than 254 characters
            {
                "links": {},
                "error": {
                    "reference": "357a24b5-eb48-45c3-9527-9718506e6e10",
                    "detail": "Check the request for invalid values or missing parameters.",
                    "type": "validation",
                    "title": "Invalid request attributes",
                    "validationDetails": [
                        {
                            "title": "Validation error",
                            "constraint": "NotBlank",
                            "attributePath": "name",
                            "detail": "must not be blank",
                            "invalidValue": ""
                        },
                        {
                            "title": "Validation error",
                            "constraint": "Size",
                            "attributePath": "name",
                            "detail": "size must be between 1 and 254",
                            "invalidValue": ""
                        }
                    ],
                    "status": 400
                }
            }

+ Response 400 (application/json)

            // when empty privileges were provided
            {
                "links": {},
                "error": {
                    "reference": "55973236-1b1a-4d76-a62d-360f5d9a1e29",
                    "detail": "Check the request for invalid values or missing parameters.",
                    "type": "validation",
                    "title": "Invalid request attributes",
                    "validationDetails": [
                        {
                            "title": "Validation error",
                            "constraint": "NotEmpty",
                            "attributePath": "privileges",
                            "detail": "must not be empty",
                            "invalidValue": "[]"
                        }
                    ],
                    "status": 400
                }
            }

+ Response 400 (application/json)

            // when privilege keys that don't exist were referenced
            {
                "links": {},
                "error": {
                    "reference": "89f517a8-7d8e-4579-8879-5c6bbdd8fd5a",
                    "detail": "Check the request for invalid values or missing parameters.",
                    "type": "validation",
                    "title": "Invalid request attributes",
                    "validationDetails": [
                        {
                            "title": "Validation error",
                            "constraint": "Unknown privileges: My.privilege",
                            "attributePath": "privileges",
                            "detail": "Unknown privileges: My.privilege",
                            "invalidValue": "[My.privilege]"
                        }
                    ],
                    "status": 400
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to edit roles
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 409 (application/json)

        // when a role with the same name already exists
        {
            "links": {},
            "error": {
                "reference": "f3c9e0d7-1c86-4da3-916f-617d839d2da5",
                "detail": "A role with name 'My new role' already exists.",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

### Get a role [GET /api/v1/roles/{id}]

Returns a role that Acrolinx identified by its *id* in the database.

+ Parameters
    + id: `f608876c-a943-4ad2-82c1-e59df943ce41` (string, required) - UUID of the role, unique identifier

+ Request

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (Role)

    + Body

            {
                "links": {},
                "data": {
                    "id": "f608876c-a943-4ad2-82c1-e59df943ce41",
                    "name": "ExampleRole",
                    "privileges": [
                        "Dashboard.logon"
                    ],
                    "default": false
                }
            }

+ Response 403 (application/json)

        // when the user doesn't have the privilege to view roles
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the specified role ID can't be found
        {
        "links": {},
            "error": {
                "reference": "9396654f-08b2-461d-80f9-d8b492786186",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

### Update a role [PUT /api/v1/roles/{id}]

Updates a role that Acrolinx identified by its *id* in the database.

**Note:**
- To update roles, you need the privilege `UserAndRoles.editUser`.
- You can't edit preconfigured roles!
    - Acrolinx comes with a number of preconfigured roles that many customers use.
- You can use one request to update role attributes individually or completely. The request will ignore missing attributes or attributes with `null` values.

+ Parameters
    + id: `f608876c-a943-4ad2-82c1-e59df943ce41` (string, required) - UUID of the role, unique identifier

+ Request Update entire model (application/json)

    You can use one request to update all attributes of a role.

    **Note:** Check the other request examples to see how to update individual attributes and validations.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (CreateOrUpdateRole)

    + Body

            {
                "name": "Preferred name",
                "privileges": [
                    "Dashboard.logon"
                ],
                "default": false
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (Role)

    + Body

            {
                "links": {},
                "data": {
                    "id": "f608876c-a943-4ad2-82c1-e59df943ce41",
                    "name": "Preferred name",
                    "privileges": [
                        "Dashboard.logon"
                    ],
                    "default": false
                }
            }

+ Response 403 (application/json)

        // when you don't have the privilege to edit roles
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the role couldn't be identified by its *id* in the database
        {
        "links": {},
            "error": {
                "reference": "5caccf73-faa9-4176-b931-8869392a2c1b",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }


+ Request Update role name (application/json)

    You can update the name of a role.

    In this example, the name will be changed for the role `ExampleRole`, which was identified by its *id* in the database.

    **Note:**
    - The name needs to be unique and must be between 1 and 254 characters.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)
        + name (string, required)

    + Body

            {
                "name": "Preferred name"
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (Role)

    + Body

            {
                "links": {},
                "data": {
                    "id": "f608876c-a943-4ad2-82c1-e59df943ce41",
                    "name": "Preferred name",
                    "privileges": [
                        "Dashboard.logon"
                    ],
                    "default": false
                }
            }

+ Response 400 (application/json)

            // when an empty name was provided or the name provided is longer than 254 characters
            {
                "links": {},
                "error": {
                    "reference": "b22b60a5-6ee4-4f4d-90fb-8a64ae4e697a",
                    "detail": "Check the request for invalid values or missing parameters.",
                    "type": "validation",
                    "title": "Invalid request attributes",
                    "validationDetails": [
                        {
                            "title": "Validation error",
                            "constraint": "Size",
                            "attributePath": "name",
                            "detail": "size must be between 1 and 254",
                            "invalidValue": ""
                        },
                        {
                            "title": "Validation error",
                            "constraint": "NotBlank",
                            "attributePath": "name",
                            "detail": "must not be blank",
                            "invalidValue": ""
                        }
                    ],
                    "status": 400
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when the user doesn't have the privilege to edit roles
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the role couldn't be identified by its *id* in the database
        {
        "links": {},
            "error": {
                "reference": "5caccf73-faa9-4176-b931-8869392a2c1b",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

+ Response 409 (application/json)

        // when you update a preconfigured built-in role
        {
            "links": {},
            "error": {
                "reference": "677ece6e-d34a-4148-a05a-6b69fa8ab16e",
                "detail": "Role 'Term Browser User(uuid=fdcd7fc6-9715-42f8-a947-88812bc02b2a privileges=[Termbrowser.logon [TERM_BROWSER] implies [Terminology.read [TERM_MANAGEMENT] implies [Dashboard.logon, Terminology.downloadImages [TERM_MANAGEMENT]]]])' is an immutable built-in role and cannot be changed.",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

        // when a role with the same name already exists
        {
            "links": {},
            "error": {
                "reference": "f3c9e0d7-1c86-4da3-916f-617d839d2da5",
                "detail": "A role with name 'Preferred name' already exists.",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }


+ Request Update the privileges that belong to a role (application/json)

    You can use roles to update the privileges that are assigned to a user.

    In this example, the `UserAndRoles.read` privilege will be assigned to the role `ExampleRole`. The role was identified by its *id* in the database.

    **Note:**
    - A role needs to have at least one privilege assigned.
    - You can add or remove privileges. Acrolinx completely replaces every privilege.
    - There might be interdependencies with other privileges.
    - All users with that particular role will automatically inherit any changes to that role.
    - You need to reference existing privileges. See [Get All Privileges](###Get_all_privileges).

    **Warning:** This action **permanently** updates the privileges that belong to a role.
    When you change the privileges for a role, all users with that role will get the updated set of privileges.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)
        + privileges (array[string], required)

    + Body

            {
                "privileges": [
                    "Dashboard.logon",
                    "UserAndRoles.read"
                ]
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (Role)

    + Body

            {
                "links": {},
                "data": {
                    "id": "f608876c-a943-4ad2-82c1-e59df943ce41",
                    "name": "ExampleRole",
                    "privileges": [
                        "UserAndRoles.read",
                        "Dashboard.logon"
                    ],
                    "default": false
                }
            }

+ Response 400 (application/json)

        // when an unknown privilege is provided in the request ("Example.privilege")
        {
            "links": {},
            "error": {
                "reference": "bc9b2e2f-1130-4ab5-8127-d9faf7f09485",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "Unknown privileges: Example.privilege",
                        "attributePath": "privileges",
                        "detail": "Unknown privileges: Example.privilege",
                        "invalidValue": "[Dashboard.logon, UserAndRoles.read, Example.privilege]"
                    }
                ],
                "status": 400
            }
        }

+ Response 400 (application/json)

        // when empty privileges are provided in the request
        {
            "links": {},
            "error": {
                "reference": "58629cdc-3102-4ff2-973b-68eb82ef2ea0",
                "detail": "Check the request for invalid values or missing parameters.",
                "type": "validation",
                "title": "Invalid request attributes",
                "validationDetails": [
                    {
                        "title": "Validation error",
                        "constraint": "NotEmpty",
                        "attributePath": "privileges",
                        "detail": "must not be empty",
                        "invalidValue": "[]"
                    }
                ],
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to edit roles
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the role couldn't be identified by its *id* in the database
        {
        "links": {},
            "error": {
                "reference": "5caccf73-faa9-4176-b931-8869392a2c1b",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

+ Response 409 (application/json)

        // when you update a preconfigured built-in role
        {
            "links": {},
            "error": {
                "reference": "677ece6e-d34a-4148-a05a-6b69fa8ab16e",
                "detail": "Role 'Term Browser User(uuid=fdcd7fc6-9715-42f8-a947-88812bc02b2a privileges=[Termbrowser.logon [TERM_BROWSER] implies [Terminology.read [TERM_MANAGEMENT] implies [Dashboard.logon, Terminology.downloadImages [TERM_MANAGEMENT]]]])' is an immutable built-in role and cannot be changed.",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

+ Request Add a default role (application/json)

    You may want to add a default role so that you can automatically assign it to newly created users.

    In this example, the `default` attribute will be updated for the role `ExampleRole`. The role was identified by its *id* in the database.

    **Note:**
    - You can have multiple default roles.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)
        + default (boolean, required) - Possible values are 'true' or 'false'

    + Body

            {
                "default": true
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (Role)

    + Body

            {
                "links": {},
                "data": {
                    "id": "f608876c-a943-4ad2-82c1-e59df943ce41",
                    "name": "ExampleRole",
                    "privileges": [
                        "Dashboard.logon"
                    ],
                    "default": true
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to edit roles
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the role couldn't be identified by its *id* in the database
        {
        "links": {},
            "error": {
                "reference": "f608876c-a943-4ad2-82c1-e59df943ce41",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

+ Request Remove a role from defaults (application/json)

    You may want to remove a default role so it isn't automatically assigned to newly created users.

    In this example, the `default` attribute will be updated for the role `ExampleRole`. The role was identified by its *id* in the database.

    + Headers

            X-Acrolinx-Auth: your_access_token

    + Attributes (object)
        + default (boolean, required) - Possible values are 'true' or 'false'

    + Body

            {
                "default": false
            }

+ Response 200 (application/json)

    + Attributes (object)
        + links (object)
        + data (Role)

    + Body

            {
                "links": {},
                "data": {
                    "id": "f608876c-a943-4ad2-82c1-e59df943ce41",
                    "name": "ExampleRole",
                    "privileges": [
                        "Dashboard.logon"
                    ],
                    "default": false
                }
            }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to edit roles
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

### Delete a role [DELETE /api/v1/roles/{id}]

This method lets you delete a specified role based on its *id*.

**Note:** You can only successfully delete a role if all of the following conditions are met:
- The role isn't a preconfigured built-in role such as "Author", "Super Administrator", or "Term Browser".
- The role isn't a default role.
- The role isn't currently assigned to one or more users.

+ Parameters
    + id: `f608876c-a943-4ad2-82c1-e59df943ce41` (string, required) - UUID of the role, unique identifier

+ Request Delete by id

    + Headers

            X-Acrolinx-Auth: your_access_token

+ Response 204

+ Response 400 (application/json)

        // when the request is invalid because of a typo, for example
        {
            "links": {},
            "error": {
                "reference": "a0b499dc-2511-4aa7-8a4e-c386d60b7800",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Bad Request",
                "status": 400
            }
        }

+ Response 401 (application/json)

        // when the access token in the request is missing or invalid
        {
            "links": {},
            "error": {
                "detail": "Valid authentication has either not been provided or is insufficient.",
                "type": "auth",
                "title": "Invalid authentication",
                "status": 401
            }
        }

+ Response 403 (application/json)

        // when you don't have the privilege to delete roles
        {
        "links": {},
            "error": {
                "reference": "f92270f4-ffe8-4104-87d5-ca457fa17cb7",
                "detail": "The user does not have the required privileges to perform the operation.",
                "type": "insufficientPrivileges",
                "title": "Insufficient privileges",
                "status": 403
            }
        }

+ Response 404 (application/json)

        // when the role couldn't be identified by its *id* in the database
        {
        "links": {},
            "error": {
                "reference": "5caccf73-faa9-4176-b931-8869392a2c1b",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Not Found",
                "status": 404
            }
        }

+ Response 409 (application/json)

        // when the preconditions to delete a role aren't met
        {
            "links": {},
            "error": {
                "reference": "7ca66314-1341-4b29-848a-fc53a14b6401",
                "detail": "An unspecific client error occurred.",
                "type": "client",
                "title": "Conflict",
                "status": 409
            }
        }

# Group Document API

A document is an entity that associates names and characteristics that identify a document with an ID. It also contains the custom document information.

Typical program flow:

1. A user opens a document in an editor.
2. The integration uses create or retrieve document information to check if the user has to fill out the custom fields.
    If the user has to fill out custom fields, the API returns all fields to fill out and the set values.
3. The integration requests the user to fill out the custom fields.
4. The integration sets the new custom fields either using the update document function or while submitting a check request.

## Document [/api/v1/document/{id}]
### Get document [GET]

This method provides Document which was found in the database.

+ Parameters
    + id: `99576707-ed8c-44b6-82b8-c3ced8f349d1` (string, required) - document id

+ Response 200 (application/json)

        {
            "data": {
                "id": "283ab1e075f21a",
                "customFields": [
                    {
                        "displayName": "Project ID",
                        "key": "projectId",
                        "value": null,
                        "required": true
                    }
                ],
                "displayInfo": {
                    "reference": "abc.md"
                }
            }
        }

### Update custom document fields [PUT]

+ Parameters

    + id: `99576707-ed8c-44b6-82b8-c3ced8f349d1` (string, required) - custom document field id to update

+ Request (application/json)

        {
            "reference": "C:\\abc.md",
            "contentType": "E-Mail",
            "customFields": [
                {
                    "key": "projectId",
                    "value": "Marketing Campaign"
                }
            ],
            "displayInfo": {
                "reference": "abc.md"
            }
        }


+ Response 200 (application/json)

        {
            "data": {
                "id": "283ab1e075f21a",
                "reference": "C:\\abc.md",
                "contentType": "E-Mail",
                "customFields": [
                    {
                        "displayName": "Project ID",
                        "key": "projectId",
                        "value": "Marketing Campaign",
                        "required": true
                    }
                ],
                "displayInfo": {
                    "reference": "abc.md"
                }
            }
        }

## Document API capabilities [GET /api/v1/document/capabilities]

Use this method to discover the configuration and capabilities of the document API.
Available information includes the configured document custom fields.

+ Response 200 (application/json)
    + Attributes
        + data (object)
        + links (object)

# Group Monitoring API

The resources in this group provide information about the health and performance of Acrolinx.
Accessing this information requires the privilege "Access to monitoring API." Not all users have this privilege. 
Make sure the user associated with your API token has the relevant privileges.

To quickly check your privileges, see if the [metrics index](#monitoring-api-get-available-metrics)
contains links. Read more about privilege management in the
[Acrolinx documentation](https://support.acrolinx.com/hc/en-us/sections/10210965582994-User-Management).

## Get available metrics [GET /api/v1/monitoring]

Lists available metrics according to the privileges of the API user. If access is granted a link to
the metrics resource will be added to the links hash. The following relations are currently available:

|Key             | Target
|----------------|-----------------
|`checkMetrics`  |[check monitoring resource](#monitoring-api-get-check-metrics)
|`healthMetrics` |[server health monitoring resource](#monitoring-api-get-health-metrics)

+ Response 200 (application/json)

        {
          "links": {
            "checkMetrics": "/api/v1/monitoring/checks",
            "healthMetrics": "/api/v1/monitoring/health"
          }
        }

## Get check metrics [GET /api/v1/monitoring/checks]

Provides a summary of the checking activity of Acrolinx.

|Field                    |Contents
|-------------------------|-------------------
|`receivedChecks`         |Total number of checks received by the platform.
|`successfulChecks`       |Total number of completed checks that didn't result in an error.
|`failedChecks`           |Total number of completed checks that resulted in an error.
|`unparseableDocuments`   |Total number of checks that failed due to parsing errors.
|`currentQueueLength`     |Current number of checks waiting for a free language server.
|`totalQueueTime`         |Total time, in seconds, check requests waited for a free language server.


+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + receivedChecks: 54132 (number) - Total number of checks received
            + successfulChecks: 54130 (number) - Total number of successful checks
            + failedChecks (number): 2 - Total number of failed checks
            + unparseableDocuments: 2 (number) - Total number of checks failed due to parsing errors
            + currentQueueLength: 0 (number) - Current number of waiting checks
            + totalQueueTime: 1563 (number) - Total time checks spent waiting


## Get health metrics [GET /api/v1/monitoring/health]

A general summary of the health of Acrolinx.

|Field                    |Contents
|-------------------------|-------------------
|`languagesReady`         |A hash containing all configured languages as keys. If Acrolinx is ready to check in a language, its value will be true.

+ Response 200 (application/json)

        {
            "data": {
                "languagesReady": {
                    "en": true,
                    "fr": true,
                    "ja": false
                }
            }
        }

## Get health status [GET /api/v1/monitoring/health/status]

This method returns a successful response when at least one language server is available for checking.
This API response will only contain `200` response code. You don't need
the privilege "Access to monitoring API" to use this API.

+ Response 200

+ Response 503

        {
            "links": {},
            "error": {
                "reference": "abee2169-66ce-4566-b21a-f086d0c2c82a",
                "detail": "Not all languages are available for checking.",
                "type": "server",
                "title": "Service Unavailable",
                "status": 503
            }
        }

## Get health liveliness [GET /api/v1/monitoring/health/live]

This returns a successful response when Acrolinx can accept and process web requests.
This method doesn't tell you if Acrolinx is ready to process check requests. To get that information,
you can make an API call to `api/v1/monitoring/health/status`.

This API response will contain the plain-text message "OK" and a `200` response code. You don't need
the "Access to monitoring API" privilege to use this API. If a response is unsuccessful,
you'll see a response other than `200`.

+ Response 200 (text/plain)

        OK

# Data structures

## Role (object) 
+ id (string) - UUID 
+ name (string) - Name of the role
+ privileges (array[string]) - Belonging privileges of the role
+ default (boolean) - Indicates that the role is assigned to new users by default [ true | false ]

## CreateOrUpdateRole (object) 
+ name (string, required) - Name of the role
+ privileges (array[string], required) - Belonging privileges of the role
+ default (boolean, optional) - Indicates that the role is assigned to new users by default [ true | false ]

## User (object)
+ id (string) - UUID
+ username (string) - The username
+ fullName (string) - The full name of the user
+ createdOn (string) - The ISO8601 timestamp indicating when the user was created
+ lastIntegrationAccess (string) - The ISO8601 timestamp indicating when the last integration access occurred
+ licenseType (string) - Indicates the type of license as one of ['named' | 'concurrent' | 'builtin']
+ licenseStatus (string) - The license status
+ activeTokenId (string) - Displays the currently active API token's id or an empty string if there’s no active token
+ checkingFrequency (UserStatus) - Gives a rough idea of the pattern of checking frequency across a user's lifetime in days
+ properties (object) - Key/Value pair of properties
+ roles (array[Role]) - List of assigned roles
+ idpUser (boolean) - Indicates whether the user has any linked identity providers
+ staffUser (boolean) - Indicates whether the user is an Acrolinx staff member
+ rolesSetByIdp (boolean) - Indicates whether the user has their roles managed by their identity provider
+ customFields (array[CustomField]) - List of custom fields

### UserStatus (enum)
+ `frequent` - Perform 1 more check than regular users.
+ `infrequent` - Perform fewer checks than regular users.
+ `regular` - Performs 1 check in 24 hours (plus/minus 25%) on average.

## CreateUser (object)
+ username (string) - The unique username, maximum length 255 characters
+ fullName (string) - The full name of the user, maximum length 255 characters (optional)
+ password (string) - The user password, length between 1 and 128 characters (optional)
+ licenseType (string) - Indicates the type of license as one of ['named' | 'concurrent'] (optional)
+ roles (array[Role]) - List of assignable roles (optional)

### CustomField (object)
+ key (string) - The unique key of the custom field 
+ displayName (string) - The name to be displayed
+ inputType (string) - Indicates the origin of the field ['required' | 'optional' | 'externallyProvided']
+ type (string) - Indicates the type ['list' | 'text']
+ value (string) - The value of the field
+ possibleValues (array[string]) - List of possible valid values

### UserApiTokenCreateResponse
+ type: "api" (string)
+ issuedAt (string) - The ISO8601 timestamp indicating when the token was issued
+ expiresAt (string) - The ISO8601 timestamp indicating when the token will expire
+ token (string) - The generated API token (JWT)

### BulkCreateUser (object)
+ users (array[CreateUser]) - List of users to be created

## BulkResult
+ status (number) - The resulting HTTP success code of the operation performed on the object
+ id (string) - The generated UUID of the object
+ location (string) - The href location of the affected object

## BulkError
+ status (number) - The resulting HTTP error code of the operation performed on the object
+ id (string) - An associated unique identifier of the object involved in the error
+ type (string) - Indicates the type of the error ['client' | 'server']
+ title (string) - The title of the error message
+ detail (string) - More details on the actual error and the potential cause
+ reference (string) - UUID for internal error logging reference

## BulkResultResponse (object)
+ results (array[BulkResult])
+ errors (array[BulkError])

## LicenseStatistics
+ named (Named)
+ concurrent (Concurrent)

### Named
+ licensed (number) - The total number of named licenses available
+ active (number) - The number of active named users
+ inactive (number) - The number of inactive named users
+ available (number) - The number of available licenses (licensed - active)

### Concurrent
+ licensed (number) - The total number of concurrent licenses available
+ existing (number) - The number of concurrent licenses used

### Pagination
+ prev (string) - URI of the previous page
+ next (string) - URI of the next page
+ first (string) - URI of the first page
+ last  (string) - URI of the last page

## RandomPassword
+ value (string) - a random, policy-compliant password

## FindTermsRequest
+ surface (string)
+ language (string)
+ domain (string)
+ entryId (string)
+ customCriteria (array[string])
+ format (string, required)
+ withSchema (boolean)

## SearchEntriesRequest
+ critera (SearchEntriesCriteria)

### SearchEntriesCriteria
+ domains (array[string])

## SearchEntriesResult
+ entries (array[SearchEntryResult])
+ search (SearchEntriesRequest)
+ totalResultCount (number)

### SearchEntryResult
+ uuid (string)
+ id (string)

## SearchRequest (object)
+ criteria (SearchRequestCriteria)
+ pagination (SearchRequestPagination)

### SearchRequestCriteria (object)
+ name (string)
+ language (string)
+ domains (array[string])
+ filter (string)

### SearchRequestPagination (object)
+ offset (number)
+ limit (number)

## SearchResult (object)
+ terms (array[Term])
+ search (SearchRequest)
+ totalResultsCount (number)

### Term (object)
+ name (string)
+ status (string)
+ domains (array[string])

# Group Reporting API

The reporting API provides direct access to raw check data and raw issue data.
You can download the data in CSV or JSON format and add it to your preferred analysis tool.

### Restrictions
#### Available data
Default: 12 months

You can download data from the past 12 months by default. Contact Acrolinx Support for more information.

#### Time limit

You can only download 31 days of data per request.

#### Concurrent requests
Default: 3 requests per tenant

This limits the number of concurrent downloads. The default is 3 concurrent downloads.
If you exceed the quota, you'll get a 429 status code. The response will include the headers Retry-After, RateLimit-Limit, and RateLimit-Remaining.

#### Download volume
Default: 1000 days of raw check data and 1000 days of raw issue data. The data will replenish at a rate of 5 days of data per day.

If you download any amount of data for a specific day, that day counts toward the default. This includes empty days. The 1000-day default is designed to give you access to all available historic data.

The quota is set for each type of data. For example, when you download check data it won't affect the amount of issue data you can download.

If you exceed the download quota, you'll get a 429 status code. The response will include the headers Retry-After, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset.

#### Date time format
The date time is in UTC format.

**Note:** To access the Reporting API, you'll need to be authorized and authenticated with an access token. Before you get started with the Reporting API, review the [authentication and authorization](https://acrolinxapi.docs.apiary.io/#introduction/authentication-and-authorization) requirements.

## Get check data [GET /api/v1/reporting/data/checks{?start,end}]

##### Download check data as a CSV file

You can access the data with cURL.

**Note:** If no data is available, the CSV file will contain headers with zero rows of data. For example, data is only available if checks were run in the requested time range.

```
curl \
    'https://<replace_your_host_address>/api/v1/reporting/data/checks?start=<replace_start_date>&end=<replace_end_date>' \
    -H "X-Acrolinx-Auth: <replace_your_access_token>" \
    -o <replace_file_name>.csv
```

##### Download check data as a CSV file with only a subset of fields

```
curl \
    'https://<replace_your_host_address>/api/v1/reporting/data/checks?start=<replace_start_date>&end=<replace_end_date>&fields=Check%20ID%2CCheck%20start%20time%2CWords%2CAcrolinx%20Score' \
    -H "X-Acrolinx-Auth: <replace_your_access_token>" \
    -o <replace_file_name>.csv
```

The downloaded data has only `Check ID`, `Check start time`, `Words` and `Acrolinx Score fields`.

#####  Download check data as a JSON file

You can access the data with cURL. To download the data in JSON format, add the header "Accept:application/json" in a request.

```
curl \
    'https://<replace_your_host_address>/api/v1/reporting/data/checks?start=<replace_start_date>&end=<replace_end_date>' \
    -H "X-Acrolinx-Auth: <replace_your_access_token>" \
    -H "Accept: application/json"
    -o <replace_file_name>.json
```

#####  Download check data as a JSON file with only a subset of fields

```
curl \
    'https://<replace_your_host_address>/api/v1/reporting/data/checks?start=<replace_start_date>&end=<replace_end_date>&fields=checkId%2CcheckStartTime%2Cwords%2CacrolinxScore
' \
    -H "X-Acrolinx-Auth: <replace_your_access_token>" \
    -H "Accept: application/json"
    -o <replace_file_name>.json
```

The downloaded data has only `checkId`, `checkStartTime`, `words` and `acrolinxScore`.

### CSV data structure for checks
|Column name|Data type|Description|Length|
|----------------|------------|------------|------------|
|Check ID|string|Unique check ID|36|
|Check start time|string|Start time of the check in UTC format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, for example, `2022-08-01T23:49:14.627Z`||
|Language|string|Checking language|255|
|Scorecard URI|string|Uniform Resource Identifier (URI) of the Scorecard|255|
|File ID|string|Unique file ID|36|
|Content reference|text|The first time you run a check, Acrolinx assigns the file a content reference. Acrolinx treats files with the same content reference as the same file.||
|File path|string|The file's location when it’s first checked|255|
|File name|string|Name of the file|255|
|Content ID|string|Unique check ID for batch checks|255|
|Acrolinx Score|number|Overall Acrolinx Score|255|
|Acrolinx Score color|string|Color coding of the Acrolinx Score|255|
|All issues|number|Count of all issues found||
|Words|number|Number of words in the file||
|Sentences|number|Number of sentences in the file||
|Style guide|string|Name of the style guide used for checking|255|
|Style guide ID|string|Unique style guide ID|36|
|Content group ID|string|Unique content group ID|36|
|Content group|string|Name of the content group|1024|
|User ID|string|Unique user ID|36|
|Full name|string|Full name of user|255|
|Integration|string|Integration used to run the check|255|
|Integration version|string|Integration version|255|
|Content profile|string|Content profile used|255|
|Check scope|string|Indicates whether a complete file or a specific selection of content is checked ['check'] or ['check selection'].|16|
|Check type|string|Indicates the specific check method used to review the file [ "batch", "interactive", "baseline", "automated" ].|16|
|Custom field {NAME}|string|Custom fields. The number of columns in the CSV file will correspond to the number of custom fields. For example, if there are 10 custom fields, the CSV file will have 10 columns for custom fields.|255|
|{NAME} goal score|number|Score for a goal. The number of columns in the CSV file will correspond to the number of goal names. For example, if there are 10 goals, the CSV file will have 10 columns for goals.||
|Clarity goal score|number|Score for the goal Clarity||
|Consistency goal score|number|Score for the goal Consistency||
|Inclusive language goal score|number|Score for the goal Inclusive language||
|Scannability goal score|number|Score for the goal Scannability||
|Spelling and grammar goal score|number|Score for the goal Spelling and grammar||
|Terminology goal score|number|Score for the goal Terminology||
|Tone goal score|number|Score for the goal Tone||
|{NAME} goal issues|number|Number of issues found for the goal. The number of columns in the CSV file will correspond to the number of goal names. For example, if there are 10 goals, the CSV file will have 10 columns for goals.||
|Clarity goal issues|number|Number of issues found for the goal Clarity||
|Consistency goal issues|number|Number of issues found for the goal Consistency||
|Inclusive language goal issues|number|Number of issues found for the goal Inclusive language||
|Scannability goal issues|number|Number of issues found for the goal Scannability||
|Spelling and grammar goal issues|number|Number of issues found for the goal Spelling and grammar||
|Terminology goal issues|number|Number of issues found for the goal Terminology||
|Tone goal issues|number|Number of issues found for the goal Tone||
|{NAME} metric score|number|Metrics suffix by actual name. If there are 10 metrics, the CSV will have 10 columns for metrics suffixes by name of the metric||

+ Request

    + Headers

            X-Acrolinx-Auth:your_access_token
            Accept:text/csv or application/json

+ Parameters
    + start: `2024-08-23` (string, required) - Date format `yyyy-MM-dd`. Download data starting from this date.
    + end: `2024-08-28` (string, required) - Date format `yyyy-MM-dd`. Download data up to this date.

+ Response 200 (text/csv)

        "Check ID","Check start time",Language,"Scorecard URI","File ID","Content reference","File path","File name","Content ID","Acrolinx Score","Acrolinx Score color","All issues",Words,Sentences,"Style guide","Style guide ID","Content group ID","Content group","User ID","Full name",Integration,"Integration version","Content profile","Check scope","Custom field department","Custom field role","Custom field status","Clarity goal score","Consistency goal score","Spelling and grammar goal score","Inclusive language goal score","Scannability goal score","Terminology goal score","Tone goal score","Clarity goal issues","Consistency goal issues","Spelling and grammar goal issues","Inclusive language goal issues","Scannability goal issues","Terminology goal issues","Tone goal issues"
        "4265b702-9a69-38ca-bb45-bcad9ee7d910",2024-01-14T23:06:58Z,en,"api/v1/checking/scorecards/4265b702-9a69-38ca-bb45-bcad9ee7d910","9d38800b-89ae-396c-ae11-1de419f13a8f",Yak-1,,Yak-1,,35,red,20,1119,47,"Essentials English 2","2bd7dbcb-5510-4cdf-b054-0f275d3047c2",,,"96e79a50-97f9-3721-a755-0e9616c26a0b","AbcFull XyzName",webchecker,v1,"f5b8573c-e603-46d7-8af0-512d199d478b",check,developers,junior,draft,57,6,76,40,19,45,42,3,2,8,2,5,5,3
        "0521406f-ccf1-3acf-904a-7452766df8d7",2024-01-15T05:34:06Z,en,"api/v1/checking/scorecards/0521406f-ccf1-3acf-904a-7452766df8d7","77ad4993-80f1-31ec-9aef-1a33d2021a86",Su-22,,Su-22,,52,yellow,20,504,41,"Essentials English 2","2bd7dbcb-5510-4cdf-b054-0f275d3047c2","710eed98-732b-3668-8a67-f4294d9a7ff4",Wade,"96e79a50-97f9-3721-a755-0e9616c26a0b","AbcFull XyzName",webchecker,v1,"f5b8573c-e603-46d7-8af0-512d199d478b",check,developers,senior,draft,15,64,84,42,43,30,85,4,2,6,6,3,0,9

+ Response 200 (application/json)


    + Body
    
            {
                "checks":
                [
                    {
                            "checkId": "895ceca3-7a1c-390d-b8d6-02a53a54e0d5",
                            "checkStartTime": "2023-11-14T21:32:22Z",
                            "language": "ja",
                            "scorecardUri": "api/v1/checking/scorecards/895ceca3-7a1c-390d-b8d6-02a53a54e0d5",
                            "fileId": "8d1bb0a8-612e-30bc-8b6d-ea9fedba138c",
                            "contentReference": "Ju-88",
                            "filePath": "",
                            "fileName": "Ju-88",
                            "contentId": null,
                            "acrolinxScore": 53,
                            "acrolinxScoreColor": "yellow",
                            "allIssues": 20,
                            "words": 1851,
                            "sentences": 100,
                            "styleGuide": "Technical English",
                            "styleGuideId": "3dd6bde9-a08b-4681-9e91-55b9ff4fc802",
                            "contentGroupId": "66e82845-c22c-3997-93f5-d3cc1d9c2e5d",
                            "contentGroup": "Connington of Griffin's Roost",
                            "userId": "4564a62d-a947-3a61-88d4-5fdb89e281e1",
                            "fullName": "abc fullname",
                            "integration": "MS word",
                            "integrationVersion": "v1",
                            "contentProfile": "f5b8573c-e603-46d7-8af0-512d199d478b",
                            "checkScope": "check",
                            "checkType": "interactive",
                            "customFields": {
                                "role": "senior",
                                "depArtment": "developers",
                                "status": "draft"
                            },
                            "goals": [
                                {
                                    "id": "CLARITY",
                                    "score": 34,
                                    "issues": 2
                                },
                                {
                                    "id": "CORRECTNESS",
                                    "score": 75,
                                    "issues": 9
                                },
                                {
                                    "id": "CONSISTENCY",
                                    "score": 83,
                                    "issues": 6
                                },
                                {
                                    "id": "INCLUSIVE",
                                    "score": 64,
                                    "issues": 0
                                },
                                {
                                    "id": "TONE",
                                    "score": 20,
                                    "issues": 9
                                },
                                {
                                    "id": "SCANNABILITY",
                                    "score": 23,
                                    "issues": 2
                                },
                                {
                                    "id": "TERMINOLOGY",
                                    "score": 72,
                                    "issues": 9
                                }
                            ],
                            "metricScores": {}
                    }                       
                ]
            }
            
    + Attributes
        + checks (array)
            + (object)
                + checkId (string) - Unique check ID
                + checkStartTime (string) - Start time of the check in the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, for example, `2022-08-01T23:49:14.627Z`
                + language (string) - Checking language
                + scorecardUri (string) - Uniform Resource Identifier (URI) of the Scorecard
                + fileId (string) - Unique file ID
                + contentReference (string) - The first time you run a check, Acrolinx assigns the file a content reference. Acrolinx treats files with the same content reference as the same file.
                + guidelineName (string) - Name of the guideline
                + filePath (string) - The file's location when it’s first checked
                + fileName (string) - Name of the file
                + contentId (string) - Unique check ID for batch checks
                + acrolinxScore (number) - Overall Acrolinx Score
                + acrolinxScoreColor (string) - Color coding of the Acrolinx Score
                + allIssues (number) - Count of all issues found
                + words (number) - Number of words in the file
                + sentences (number) - Number of sentences in the file
                + styleGuide (string) - Name of the style guide used
                + styleGuideId (string) - Unique style guide ID
                + contentGroupId (string) - Unique content group ID
                + contentGroup (string) - Name of the content group
                + userId (string) - Unique user ID
                + fullName (string) - Full name of user
                + integration (string) - Integration used to run the check
                + integrationVersion (string) - Integration version
                + contentProfile (string) - Content profile used
                + checkScope (string) - Indicates whether a complete file or a specific selection of content is checked ['check'] or ['check selection']
                + checkType (string) - Indicates the specific check method used to review the file [ "batch", "interactive", "baseline", "automated" ]
                + customFields (object) - Key-value pair of custom fields
                + goals (array) - List of goals
                    + (object)
                        + id (string) - ID of the goal
                        + score (number) - Score for a goal
                        + issues (number) - Count of all issues found for a goal
                + metricScores (object) - Metric score


+ Response 400 (application/json)

        {
            "code": 400,
            "message": "Provide a start date."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "Provide an end date."
        }

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "2024-06-31 is an invalid start date. Make sure the date entered is in the format 'yyyy-MM-dd' and corresponds with the actual number of days in the month."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "2024-Sept-09 is an invalid end date. Make sure the date entered is in the format 'yyyy-MM-dd' and corresponds with the actual number of days in the month."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "Invalid 'start' date 2024-08-29 and 'end' date 2024-08-28. The 'start' date must be before the 'end' date."
        }

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "Invalid 'end' date 2024-08-28. The 'end' date must be before 2024-08-28. The most recent data available for download is from yesterday."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "You can only download data from the past 12 months. Provide a different start date."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "You can only download 31 days of data at a time. Adjust the date range."
        } 

+ Response 403 (application/json)

        {
            "code": 403,
            "message": "Unauthorized access to reporting API. Contact your Acrolinx administrator for more information."
        } 

+ Response 403 (application/json)

        {
            "code": 403,
            "message": "The Reporting API feature is inactive."
        } 
        
+ Response 409 (application/json)

        {
            "code": 409,
            "message": "Data before 2024-08-01 is available to download. To download data up to 2024-08-01, adjust the dates."
        } 

+ Response 409 (application/json)

        {
            "code": 409,
            "message": "No data is available for download. Try again later."
        } 

+ Response 429 (application/json)

        {
            "code": 429,
            "message": "Too many requests. Try again later. If you still have trouble, contact Acrolinx Support."
        } 

+ Response 429 (application/json)

        {
            "code": 429,
            "message": "Download volume reached. The data will replenish at a rate of 5 days of data per day."
        } 
        
+ Response 500 (application/json)

        {
            "code": 500,
            "message": "Something went wrong. Try again or contact Acrolinx Support."
        } 

## Get issues data [GET /api/v1/reporting/data/issues{?start,end}]

##### Download issue data as a CSV file

You can access the data with cURL. 

**Note:** If no data is available, the CSV file will contain headers with zero rows of data. For example, data won't be available if no checks were run in the requested time range.

```
curl \
    'https://<replace_your_host_address>/api/v1/reporting/data/issues?start=<replace_start_date>&end=<replace_end_date>' \
    -H "X-Acrolinx-Auth: <replace_your_access_token>" \
    -o <replace_file_name>.csv
```

##### Download issue data as a CSV file with only a subset of fields

```
curl \
    'https://<replace_your_host_address>/api/v1/reporting/data/issues?start=<replace_start_date>&end=<replace_end_date>&fields=Check%20ID%2CDate%2CGuideline%20ID%2CGuideline%20name' \
    -H "X-Acrolinx-Auth: <replace_your_access_token>" \
    -o <replace_file_name>.csv
```

This will download data only with the fields `Check ID`, `Date`, `Guideline ID` and`Guideline name`.

#####  Download issue data as a JSON file

You can access the data with cURL. To download the data in JSON format, add the header "Accept:application/json" in a request.

```
curl \
    'https://<replace_your_host_address>/api/v1/reporting/data/issues?start=<replace_start_date>&end=<replace_end_date>' \
    -H "X-Acrolinx-Auth: <replace_your_access_token>" \
    -H "Accept: application/json"
    -o <replace_file_name>.json
```

#####  Download issue data as a JSON file with only a subset of fields

You can access the data with cURL. To download the data in JSON format, add the header "Accept:application/json" in a request.

```
curl \
    'https://<replace_your_host_address>/api/v1/reporting/data/issues?start=<replace_start_date>&end=<replace_end_date>&fields=checkId%2Cdate%2CguidelineId%2CguidelineName' \
    -H "X-Acrolinx-Auth: <replace_your_access_token>" \
    -H "Accept: application/json"
    -o <replace_file_name>.json
```

This will download data only with the fields `checkId`, `date`, `guidelineId` and`guidelineName`.

### CSV data structure for issues
|Column name|Data type|Description|Length|
|----------------|------------|------------|------------|
|Check ID|string|Unique check ID|36|
|Date|string|Date when the issue was found. Shown in the format `yyyy-MM-dd`, for example, `2022-01-20`||
|Context|string|Sentence or paragraph where the issue occurred|1024|
|Issue|text|Content that Acrolinx highlighted||
|Structural context|string|Structural location where the issue occurred in the file|1024|
|Goal ID|string|ID of the goal|255|
|Goal name|string|Name of the goal|255|
|Guideline ID|string|Unique ID of the guideline|255|
|Guideline name|string|Name of the guideline|255|
|Language|string|Checking language|255|
|Issue type|string|Type of issue|20|
|Term|string|Actual word or phrase highlighted during the Acrolinx check|255|
|Domain or Term filter|string|Internal category for the highlighted term|255|
|Term status|string|How Acrolinx checked for the highlighted term ["admitted", "deprecated", "preferred"]. Read more about term statuses in the article [Term Settings](https://support.acrolinx.com/hc/en-us/articles/10228296536082-Term-Settings).|15|

+ Request

    + Headers

            X-Acrolinx-Auth:your_access_token
            Accept:text/csv or application/json

+ Parameters
    + start: `2024-08-23` (string, required) - Date format `yyyy-MM-dd`. Download data starting from this date.
    + end: `2024-08-28` (string, required) - Date format `yyyy-MM-dd`. Download data up to this date.

+ Response 200 (text/csv)

        "Check ID",Date,Context,Issue,"Structural context",Goal,"Goal name","Guideline ID","Guideline name",Language,"Issue type",Term,"Domain or Term filter","Term status"
        "4bbdc491-6821-3b53-8881-001553987b69",2023-10-30,"hello woorld",woorld,sentence,CONSISTENCY,"Consistency","en_CONSISTENCY_Guideline_id-9","CONSISTENCY guideline id 9 display name",en,syntax,,,
        "4bbdc491-6821-3b53-8881-001553987b69",2023-10-30,"hello woorld",woorld,sentence,INCLUSIVE,"Inclusive language","en_INCLUSIVE_Guideline_id-6","INCLUSIVE guideline id 6 display name",en,syntax,,,
        
+ Response 200 (application/json)

    + Body

            {
                "issues":
                    [
                        {
                            "checkId": "d800f541-f1b8-3df6-9a22-c565476b81c8",
                            "context": "hello woorld",
                            "issue": "woorld",
                            "structuralContext": "sentence",
                            "date": "2023-11-08",
                            "goalId": "CORRECTNESS",
                            "goalName": "Spelling and grammar",
                            "guidelineId": "en_CORRECTNESS_Guideline_id-3",
                            "guidelineName": "CORRECTNESS guideline id 3 display name",
                            "language": "en",
                            "issueType": "syntax",
                            "term": null,
                            "domainOrTermFilter": [],
                            "termStatus": null
                        },
                        {
                            "checkId": "d800f541-f1b8-3df6-9a22-c565476b81c8",
                            "context": "Acrolinx supports",
                            "issue": "Acrolinx",
                            "structuralContext": "word",
                            "date": "2023-11-08",
                            "goalId": "WORDS_AND_PHRASES",
                            "goalName": "Terminology",
                            "guidelineId": "",
                            "guidelineName": null,
                            "language": null,
                            "issueType": "terminology",
                            "term": "Acrolinx",
                            "domainOrTermFilter": [
                                "PLAIN_ENGLISH",
                                "undefined domain"
                            ],
                            "termStatus": "deprecated"
                        }                       
                    ]
            }

    + Attributes
        + issues (array)
            + (object)
                + checkId (string) - Unique check ID
                + context (string) - Sentence or paragraph where the issue occurred
                + issue (string) - Content that Acrolinx highlighted
                + structuralContext (string) - Structural location where the issue occurred in the file
                + date (string) - Date when the issue was found. Shown in the format `yyyy-MM-dd`, for example, `2022-01-20`
                + goalId (string) - ID of the goal
                + goalName (string) - English name of the goal
                + guidelineId (string) - Unique ID of the guideline
                + guidelineName (string) - Name of the guideline
                + language (string) - Checking language
                + issueType (string) - Type of issue
                + term (string) - Actual word or phrase highlighted during the Acrolinx check
                + domainOrTermFilter (array) - List of internal category for the highlighted term
                    + (string)
                + termStatus (string) - Acrolinx checked for the highlighted term ["admitted", "deprecated", "preferred"]. Read more about term statuses in the article [Term Settings](https://support.acrolinx.com/hc/en-us/articles/10228296536082-Term-Settings).

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "Provide a start date."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "Provide an end date."
        }

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "2024-06-31 is an invalid start date. Make sure the date entered is in the format 'yyyy-MM-dd' and corresponds with the actual number of days in the month."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "2024-Sept-09 is an invalid end date. Make sure the date entered is in the format 'yyyy-MM-dd' and corresponds with the actual number of days in the month."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "Invalid 'start' date 2024-08-29 and 'end' date 2024-08-28. The 'start' date must be before the 'end' date."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "Invalid 'end' date 2024-08-28. The 'end' date must be before 2024-08-28. The most recent data available for download is from yesterday."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "You can only download data from the past 12 months. Provide a different start date."
        } 

+ Response 400 (application/json)

        {
            "code": 400,
            "message": "You can only download 31 days of data at a time. Adjust the date range."
        } 

+ Response 403 (application/json)

        {
            "code": 403,
            "message": "Unauthorized access to reporting API. Contact your Acrolinx administrator for more information."
        } 

+ Response 403 (application/json)

        {
            "code": 403,
            "message": "The Reporting API feature is inactive."
        } 
+ Response 409 (application/json)

        {
            "code": 409,
            "message": "Data before 2024-08-01 is available to download. To download data up to 2024-08-01, adjust the dates."
        }   

+ Response 409 (application/json)

        {
            "code": 409,
            "message": "No data is available for download. Try again later."
        } 

+ Response 429 (application/json)

        {
            "code": 429,
            "message": "Too many requests. Try again later. If you still have trouble, contact Acrolinx Support."
        } 

+ Response 429 (application/json)

        {
            "code": 429,
            "message": "Download volume reached. The data will replenish at a rate of 5 days of data per day."
        } 

+ Response 500 (application/json)

        {
            "code": 500,
            "message": "Something went wrong. Try again or contact Acrolinx Support."
        } 

# Group Terminology API v9

## Deprecation Note

**Warning:** Communication using the SDL *MultiTerm XML* format is
deprecated. While it still works today, support can be removed at any
time.

## Configuration

Before invoking one of the Terminology API services for the SDL
MultiTerm result format, the Core Platform must be configured
correctly. This includes that there are XSL transformations from ACTIF
format to SDL MultiTerm XML and SDL MultiTerm Definition XDT. The
needed XSL style sheets will be available as part of the Core Platform
resources.

The availability of those resources can be checked in the Acrolinx
dashboard on `Style -> Term import and Export -> Custom File Format`.

## Media/Content Types

Except for application-specific XML data (ACTIF resp. SDL MultiTerm
XML/XDT data), request, and response data is usually either plain text
or in JSON format. The encoding is usually assumed to be UTF-8.

With some service methods, you can control the format of the return
values by means of the standard HTTP `Accept` header.

Service methods that accept application-specific body data rely on the
correct setting of the standard HTTP `Content-Type` header.

The supported media types are listed where applicable.

## Authentication and Authorization [/iq/services/v3/rest/core]

Before invoking any Terminology API, the Acrolinx Integration must
authorize and acquire a session. The authorization itself isn’t part
of the Terminology API. API requests without a valid session ID in the
`Authorization` HTTP header field fail with a `403 Forbbiden`
response:

```
{
    "message": "Invalid session  (no such session)",
    "errors": {
        "exception_type": "com.acrolinx.services.faults.InvalidSessionFault",
        "exception_message": "Invalid session  (no such session)"
    }
}
```

For all terminology service API methods, the user must have at least
the `Access API-based terminology applications` privilege.

### Acquiring a Session [POST /requestSession]

Using the authentication token, the integration now needs to open a
session, specifying the session-type (always `TERMINOLOGY` for usage
of the Terminology API) and the signature of the integration (see
Signatures section further up).

The returned session token should be used in subsequent requests to
the Terminology API. It’s valid until the session is released by the
integration or by the Core Platform. As the license limits the number
of concurrently opened sessions, an integration mustn’t forget to
release a session before acquiring a new session token.

+ Request

    + Header

            authToken: your_access_token

    + Body

            {
                "sessionType": "TERMINOLOGY",
                "clientSignature": "SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5",
                "clientInfo": {
                    "buildNumber": "unknown",
                    "clientHostname": "localhost",
                    "version": "0.1",
                    "name": "Terminology Test Client",
                    "clientHostApplication": "unknown",
                    "clientLoginName": "unknown"
                }
            }

+ Response 200 (text/plain)

        56429c06fbd5da74


### Releasing a Session [DELETE /requestSession/{id}]

A session can be released by a `DELETE` on
`/iq/services/v3/rest/core/releaseSession`, providing the session as
path parameter.

+ Parameters

    + id: `56429c06fbd5da74z` (string, required) - session ID

+ Request

    + Headers

            authToken: your_access_token


+ Response 204


## Term entries [/iq/services/v9/rest/terminology/entries/{id}]

### Get by UUID or ID [GET]

Supported media types:

- `application/vnd.acrolinx.actif+xml`: return entries as ACTIF in XML
- `application/vnd.acrolinx.mtf+xml`: return entries as SDL MultiTerm XML

Required privilege:

- Terminology View Terms

This functionality is provided by `GET` `/entries`. There are two variants of this operation:

- asking for a single UUID or ID
- asking for many UUIDs or IDs

For asking for only one entry simply append its UUID to the service
URI. This works the same way for requesting multiple entries, just
pass a comma-separated list of IDs in the URL. The server determines
by the format of the passed ID string whether it’s a UUID or an ID.

**Note:** The length of the request URL is limited by any HTTP server
implementation. Based on our tests, we don't recommend exceeding the
value of 4000 characters.

+ Parameters

    + id: `7bd1ee3f-8e46-4a1f-bd45-a3c18981f731`  (string, required)

        Either a single term entry ID or a comma-separated list of entry IDs.

+ Request ACTIF

    + Headers

            authToken: your_access_token
            Authorization: session your_session_id
            Accept: application/vnd.acrolinx.mtf+xml

+ Response 200 (application/vnd.acrolinx.actif+xml)

    + Body

            <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
            <actif xmlns="http://www.acrolinx.com" version="1.0">
                <origin date="2025-03-10T13:50:26.160Z">
                    <tool/>
                </origin>
                <data>
                    <source-languages>
                        <lang>en</lang>
                    </source-languages>
                    <entry>
                        <value field="color_concept">red</value>
                        <value field="weather">foggy</value>
                        <value field="weather">cold</value>
                        <value field="weather">cloudy</value>
                        <value field="imageURL">077061bc-d9ab-455d-a078-bb1fb648440e_f2f455eb5898c6568524f6ca87236342.jpg</value>
                        <value field="entry/id">1309938647786</value>
                        <value field="entry/uuid">459a8ff0-dfab-49d6-927f-6c456f194168</value>
                        <head>
                            <term>
                                <name>802.11n technology</name>
                                <language>en</language>
                                <value field="term/status">preferred</value>
                                <value field="term/domain">D-Link</value>
                                <value field="term/uuid">6183eceb-33e4-4b5e-b721-0ac34eb78fb4</value>
                                <value field="term/id">1309883915302</value>
                                <value field="term/frequency">0</value>
                                <value field="term/creation-date-time">2011-07-06T08:02:35.383Z</value>
                                <value field="term/creator-user-name">admin</value>
                                <value field="term/last-modification-date-time">2024-06-26T14:38:51.230Z</value>
                                <value field="term/last-modifier">peter.bernds@acrolinx.com</value>
                                <value field="processStatus">unprocessed</value>
                                <value field="gender">undefined</value>
                                <value field="partOfSpeech">undefined</value>
                                <value field="termType">undefined</value>
                                <complex-value field="term/msr">
                                    <attribute name="analysisMode">string</attribute>
                                </complex-value>
                            </term>
                        </head>
                        <term>
                            <name>802.11 network switch</name>
                            <language>en</language>
                            <value field="term/status">preferred</value>
                            <value field="term/domain">Belkin</value>
                            <value field="term/uuid">077061bc-d9ab-455d-a078-bb1fb648440e</value>
                            <value field="term/id">1309883964051</value>
                            <value field="term/frequency">0</value>
                            <value field="term/creation-date-time">2011-07-06T08:15:24.073Z</value>
                            <value field="term/creator-user-name">admin</value>
                            <value field="term/last-modification-date-time">2024-06-26T14:38:51.342Z</value>
                            <value field="term/last-modifier">peter.bernds@acrolinx.com</value>
                            <value field="processStatus">unprocessed</value>
                            <value field="color_ts">light red</value>
                            <value field="gender">undefined</value>
                            <value field="partOfSpeech">undefined</value>
                            <value field="termType">undefined</value>
                            <complex-value field="term/msr">
                                <attribute name="analysisMode">base (analyzed)</attribute>
                                <attribute name="token">network</attribute>
                                <attribute name="occurrence">1</attribute>
                                <attribute name="mcat">noun</attribute>
                            </complex-value>
                            <complex-value field="term/event">
                                <attribute name="user">admin</attribute>
                                <attribute name="date">2016-11-21T17:01:51.887Z</attribute>
                                <attribute name="type">COMMENT</attribute>
                                <attribute name="text">ttt
                                </attribute>
                            </complex-value>
                        </term>
                    </entry>
                </data>
            </actif>

+ Request SDL Multiterm format

    + Headers

            Authorization: session your_session_id
            Accept: application/vnd.acrolinx.mtf+xml

+ Response 200 (application/vnd.acrolinx.mtf+xml)

    + Body

            <?xml version="1.0" encoding="utf-8"?>
            <mtf>
                <conceptGrp>
                    <concept>13</concept>
                    <descripGrp>
                        <descrip type="ENTRY_UUID">a918fccf-4a94-4398-b260-4d792289952c</descrip>
                    </descripGrp>
                    <transacGrp>
                        <transac type="origination">admin</transac>
                        <date>2011-06-28T11:55:28+02:00</date>
                    </transacGrp>
                    <transacGrp>
                        <transac type="modification">admin</transac>
                        <date>2014-02-03T11:00:04</date>
                    </transacGrp>
                    <languageGrp>
                        <language lang="EN" type="English"/>
                        <termGrp>
                            <term>return air</term>
                            <descripGrp>
                                <descrip type="Status">preferred</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">Technical_Names</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">undefined domain</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_UUID">120bdf01-4818-4a2c-bcea-4f875b6b129a</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_ID">1371197695606</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="term/frequency">0</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Core">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Part of Speech">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="gender">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="processStatus">unprocessed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="termType">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="MORPHOSYNTACTIC_RESTRICTION"/>
                            </descripGrp>
                            <transacGrp>
                                <transac type="origination">admin</transac>
                                <date>2011-06-28T11:55:28+02:00</date>
                            </transacGrp>
                            <transacGrp>
                                <transac type="modification">admin</transac>
                                <date>2014-02-03T11:00:04</date>
                            </transacGrp>
                        </termGrp>
                    </languageGrp>
                    <languageGrp>
                        <language lang="NL" type="Dutch"/>
                        <termGrp>
                            <term>text nicht vorhanden</term>
                            <descripGrp>
                                <descrip type="Status">proposed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">undefined domain</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_UUID">680e0ea1-90f1-48ab-9ec9-5a362360692d</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_ID">1371197695622</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="term/frequency">0</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Core">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Part of Speech">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="gender">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="processStatus">unprocessed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="termType">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="MORPHOSYNTACTIC_RESTRICTION"/>
                            </descripGrp>
                            <transacGrp>
                                <transac type="origination">admin</transac>
                                <date>2011-06-28T12:11:20+02:00</date>
                            </transacGrp>
                            <transacGrp>
                                <transac type="modification">peter.bernds@acrolinx.com</transac>
                                <date>2011-07-05T10:54:28+02:00</date>
                            </transacGrp>
                        </termGrp>
                    </languageGrp>
                    <languageGrp>
                        <language lang="ES" type="Spanish"/>
                        <termGrp>
                            <term>text nicht vorhanden</term>
                            <descripGrp>
                                <descrip type="Status">proposed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">undefined domain</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_UUID">01352af7-73e6-4024-9433-930846681b56</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_ID">1371197695630</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="term/frequency">0</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Core">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Part of Speech">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="gender">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="processStatus">unprocessed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="termType">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="MORPHOSYNTACTIC_RESTRICTION"/>
                            </descripGrp>
                            <transacGrp>
                                <transac type="origination">admin</transac>
                                <date>2011-06-28T12:11:19+02:00</date>
                            </transacGrp>
                            <transacGrp>
                                <transac type="modification">peter.bernds@acrolinx.com</transac>
                                <date>2011-09-13T10:47:25+02:00</date>
                            </transacGrp>
                        </termGrp>
                    </languageGrp>
                    <languageGrp>
                        <language lang="DE" type="German"/>
                        <termGrp>
                            <term>Abluftmenge</term>
                            <descripGrp>
                                <descrip type="Status">proposed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">Technical_Names</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">undefined domain</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_UUID">44641d47-ddf3-4bb4-b1d4-a22a3fb42f64</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_ID">1371197695646</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="term/frequency">0</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Core">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Part of Speech">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="gender">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="processStatus">unprocessed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="termType">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="MORPHOSYNTACTIC_RESTRICTION"/>
                            </descripGrp>
                            <transacGrp>
                                <transac type="origination">admin</transac>
                                <date>2011-06-28T11:55:28+02:00</date>
                            </transacGrp>
                            <transacGrp>
                                <transac type="modification">admin</transac>
                                <date>2014-02-03T10:59:47</date>
                            </transacGrp>
                        </termGrp>
                    </languageGrp>
                    <languageGrp>
                        <language lang="FR" type="French"/>
                        <termGrp>
                            <term>débit d'air repris</term>
                            <descripGrp>
                                <descrip type="Status">preferred</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">Technical_Names</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">undefined domain</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_UUID">5334a674-848b-44a3-8b42-1756d38717ef</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_ID">1371197695614</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="term/frequency">0</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Core">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Part of Speech">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="gender">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="processStatus">unprocessed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="termType">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="MORPHOSYNTACTIC_RESTRICTION"/>
                            </descripGrp>
                            <transacGrp>
                                <transac type="origination">admin</transac>
                                <date>2011-06-28T11:55:28+02:00</date>
                            </transacGrp>
                            <transacGrp>
                                <transac type="modification">admin</transac>
                                <date>2014-02-03T10:59:54</date>
                            </transacGrp>
                        </termGrp>
                        <termGrp>
                            <term>débit d'évacuation</term>
                            <descripGrp>
                                <descrip type="Status">deprecated</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">Technical_Names</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">undefined domain</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_UUID">38e4ce12-4175-465e-a26f-4bb6d8a7ea15</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_ID">1371197695654</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="term/frequency">0</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Core">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Part of Speech">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="gender">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="processStatus">unprocessed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="termType">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="MORPHOSYNTACTIC_RESTRICTION"/>
                            </descripGrp>
                            <transacGrp>
                                <transac type="origination">admin</transac>
                                <date>2011-06-28T11:55:28+02:00</date>
                            </transacGrp>
                            <transacGrp>
                                <transac type="modification">admin</transac>
                                <date>2014-02-03T10:59:58</date>
                            </transacGrp>
                        </termGrp>
                    </languageGrp>
                    <languageGrp>
                        <language lang="IT" type="Italian"/>
                        <termGrp>
                            <term>text nicht vorhanden</term>
                            <descripGrp>
                                <descrip type="Status">proposed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="domain">undefined domain</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_UUID">7958d666-8511-4c0e-aef1-d0f4748d2d46</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="TERM_ID">1371197695638</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="term/frequency">0</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Core">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="Part of Speech">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="gender">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="processStatus">unprocessed</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="termType">undefined</descrip>
                            </descripGrp>
                            <descripGrp>
                                <descrip type="MORPHOSYNTACTIC_RESTRICTION"/>
                            </descripGrp>
                            <transacGrp>
                                <transac type="origination">admin</transac>
                                <date>2011-06-28T12:11:18+02:00</date>
                            </transacGrp>
                            <transacGrp>
                                <transac type="modification">admin</transac>
                                <date>2011-08-30T11:55:38+02:00</date>
                            </transacGrp>
                        </termGrp>
                    </languageGrp>
                </conceptGrp>
            </mtf>

+ Response 406

    + Body

            {
                "error": "No terminology export transformation stylesheet available for 'application/vnd.acrolinx.mtf+xml'",
                "code": "cantServeRequestedMediaType",
                "data": {}
            }

### Delete [DELETE]

Entire entries can be removed by calling DELETE on
`/entries/{entryUUID}`. If an entry existed and could be deleted
successfully, the service returns 204 (No Content). Otherwise, if
there’s no entry under the specified UUID, the service returns 410
(Gone).

Required Privilege

Terminology - Edit Terms

+ Parameters

    + id: `a918fccf-4a94-4398-b260-4d792289952c` (string, required) - the UUID of the term to delete

+ Response 410

## Editing term entries [/iq/services/v9/rest/terminology/entries]

### Create and update [PUT]

Entries and their terms can be created and updated by POSTing the
respective ACTIF or SDL MultiTerm XML representation to /entries.
Whether an existing entry is updated or a new entry created crucially
depends on the entry UUID specified in the sent data. If the entry
UUID references an existing entry in the database, all terms and
fields of the entry will be replaced by the sent data. Specifically,
if the sent entry data contains fewer terms than the existing entry in
the database, those terms missing from the sent entry data will be
deleted.

Otherwise, that is, no entry of the same UUID exists, a new entry will
be created.

Supported media types are:

* application/vnd.acrolinx.actif+xml: ACTIF in XML
* application/vnd.acrolinx.mtf+xml: SDL MultiTerm XML

Required privileges:

* Terminology - Import terms (implies "Edit terms")
* Terminology - Change the status of a term

For both creation and update, the return code is 201 (created) and the
"Location" header gets the URL of the inserted/updated entry. If the
input data doesn't contain an entry that needs to be created or
updated, you'll see a 204 (no content). If the input data contains
more than one entry (which is allowed), all entries in the input data
will be created or updated respectively. However, the "Location"
header will only contain the URL of one of them.

+ Request

    + Headers

            Authorization: session <SESSION_ID>

+ Response 200 (application/json)

    + Body

            {}

## Schema [/iq/services/v9/rest/terminology/schema]

### Get term base structure [GET]

Retrieves the structure of the Acrolinx term base.

+ Request

    + Headers

            Authorization: session your_session_id
            Accept: application/vnd.acrolinx.actif+xml

+ Response 200 (application/vnd.acrolinx.actif+xml)

    + Body

            <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
            <actif xmlns="http://www.acrolinx.com" version="1.0">
                <origin date="2025-03-10T14:06:11.978Z">
                    <tool/>
                </origin>
                <schema>
                    <categories>
                        <category name="language">
                            <item default="true">en</item>
                            <item parent="en">en-JP</item>
                            <item parent="en">en-US</item>
                            <item parent="en">en-GB</item>
                            <item>de</item>
                            <item>ja</item>
                            <item>zh</item>
                            <item parent="zh">zh-CN</item>
                            <item parent="zh">zh-TW</item>
                            <item>ar</item>
                            <item>fr</item>
                            <item>it</item>
                            <item>ko</item>
                            <item>ru</item>
                            <item>es</item>
                            <item>sv</item>
                            <item>mul</item>
                            <item>no</item>
                            <item>bg</item>
                            <item>cs</item>
                            <item>nl</item>
                            <item>pt</item>
                            <item>sprache</item>
                            <item parent="sprache">sub1</item>
                            <item parent="sprache">sub2</item>
                        </category>
                        <category name="boolean">
                            <item>true</item>
                            <item default="true">false</item>
                        </category>
                        <category name="lexical analysis mode">
                            <item default="true">string</item>
                            <item>base (analyzed)</item>
                        </category>
                        <category name="part of speech">
                            <item>adjective</item>
                            <item>adverb</item>
                            <item>noun</item>
                            <item>other</item>
                            <item>proper noun</item>
                            <item default="true">undefined</item>
                            <item>verb</item>
                        </category>
                        <category name="morphosyntactic restriction">
                            <item default="true">all</item>
                            <item>noun</item>
                            <item>verb</item>
                            <item>adjective</item>
                            <item>adverb</item>
                            <item>adposition</item>
                            <item>preposition</item>
                            <item>determiner</item>
                            <item>conjunction</item>
                            <item>pronoun</item>
                            <item>prefix</item>
                            <item>suffix</item>
                        </category>
                        <category name="domain">
                            <item>New_Words</item>
                            <item>Plain_English</item>
                            <item>Smart Tech</item>
                            <item default="true">undefined domain</item>
                            <item parent="undefined domain">even more undefined</item>
                            <item>customer</item>
                            <item parent="customer">ex customer</item>
                            <item>Special Symbols</item>
                            <item>Demo</item>
                            <item parent="Demo">Switches</item>
                            <item parent="Demo">Keitaidenwa</item>
                            <item parent="Demo">KanaKanjiUsage</item>
                            <item parent="Demo">ADSL</item>
                            <item parent="Demo">MFP</item>
                            <item parent="Demo">Drucker</item>
                            <item parent="Demo">Acrolinx</item>
                            <item parent="Demo">Standard_Terminology</item>
                            <item parent="Demo">Routers</item>
                            <item parent="Routers">Belkin</item>
                            <item parent="Routers">D-Link</item>
                            <item parent="Routers">Cisco</item>
                            <item parent="Demo">Phone</item>
                            <item>ASD-STE100</item>
                            <item parent="ASD-STE100">Technical_Names</item>
                            <item parent="Technical_Names">TN_1_Official_Parts_Information</item>
                            <item parent="Technical_Names">TN_2_Locations_On_Machines_Vehicles_Or_Equipment</item>
                            <item parent="Technical_Names">TN_3_Tools_Or_Equipment</item>
                            <item parent="Technical_Names">TN_4_Materials_Consumables_Or_Unwanted_Matter</item>
                            <item parent="Technical_Names">TN_5_Facilities_And_Infrastructure</item>
                            <item parent="Technical_Names">TN_6_Circuits_Or_Systems</item>
                            <item parent="Technical_Names">TN_7_Mathematical_Scientific_Or_Engineering_Terms</item>
                            <item parent="Technical_Names">TN_8_Navigation</item>
                            <item parent="Technical_Names">TN_9_Numbers_Units_Of_Measurement_Or_Dial_Markings</item>
                            <item parent="Technical_Names">TN_10_Quoted_Text</item>
                            <item parent="Technical_Names">TN_11_Persons_Groups_Or_Bodies</item>
                            <item parent="Technical_Names">TN_12_Body_Parts</item>
                            <item parent="Technical_Names">TN_13_Common_Personal_Effects</item>
                            <item parent="Technical_Names">TN_14_Medical_Terms</item>
                            <item parent="Technical_Names">TN_15_Documents_Or_Manuals</item>
                            <item parent="Technical_Names">TN_16_Names_Headings_And_Topics_In_Specifications</item>
                            <item parent="Technical_Names">TN_17_Technical_Records_Standards_Specifications_Or_Regulations</item>
                            <item parent="Technical_Names">TN_18_Environmental_Conditions</item>
                            <item parent="Technical_Names">TN_19_Colors</item>
                            <item parent="Technical_Names">TN_20_Damage_Terms</item>
                            <item parent="Technical_Names">TN_Unclassified</item>
                            <item parent="ASD-STE100">Technical_Verbs</item>
                            <item parent="Technical_Verbs">TV_1_Manufacturing_Processes</item>
                            <item parent="Technical_Verbs">TV_2_Computer_Processes_And_Applications</item>
                            <item parent="Technical_Verbs">TV_3_Descriptions</item>
                            <item parent="Technical_Verbs">TV_Unclassified</item>
                            <item>S1000D Bike Data Set</item>
                            <item>Dental Floss Tycoon</item>
                        </category>
                        <category name="status">
                            <item default="true">proposed</item>
                            <item parent="proposed">proposed_from_search</item>
                            <item>deprecated</item>
                            <item>admitted</item>
                            <item>preferred</item>
                            <item>non-term</item>
                            <item parent="non-term">stopword</item>
                            <item parent="non-term">no-single-term</item>
                        </category>
                        <category name="weather">
                            <item default="true">undefined</item>
                            <item>wam</item>
                            <item>cold</item>
                            <item>sunny</item>
                            <item>cloudy</item>
                            <item>foggy</item>
                            <item>rainy</item>
                            <item>hot</item>
                        </category>
                        <category name="process status">
                            <item default="true">unprocessed</item>
                            <item>provisionally processed</item>
                            <item>finalized</item>
                            <item>review requested</item>
                        </category>
                        <category name="gender">
                            <item default="true">undefined</item>
                            <item>masculine</item>
                            <item>feminine</item>
                            <item>neuter</item>
                            <item>other</item>
                        </category>
                        <category name="term type">
                            <item default="true">undefined</item>
                            <item>full form</item>
                            <item>acronym</item>
                            <item>abbreviation</item>
                            <item>short form</item>
                            <item>variant</item>
                            <item>phrase</item>
                        </category>
                        <category name="color">
                            <item default="true">undefined</item>
                            <item>red</item>
                            <item parent="red">light red</item>
                            <item parent="red">dark red</item>
                            <item parent="red">carmesin</item>
                            <item>green</item>
                            <item>blue</item>
                            <item>yellow</item>
                        </category>
                        <category name="emma">
                            <item default="true">undefined</item>
                        </category>
                    </categories>
                    <fields>
                        <entry-level>
                            <field data-type="text" builtin="true" name="entry/id"/>
                            <field data-type="uuid" builtin="true" name="entry/uuid"/>
                            <field data-type="image" name="imageURL"/>
                            <field data-type="html" name="sourceOfDefinition"/>
                            <field data-type="text" name="definition"/>
                            <field data-type="list" set-valued="true" category="weather" name="weather">
                                <default-value>hot</default-value>
                            </field>
                            <field data-type="text" name="subjectField"/>
                            <field data-type="list" set-valued="true" category="color" name="color_concept">
                                <default-value>blue</default-value>
                            </field>
                        </entry-level>
                        <term-level>
                            <field mandatory="true" data-type="list" category="status" builtin="true" name="term/status">
                                <default-value>proposed</default-value>
                            </field>
                            <field mandatory="true" data-type="list" set-valued="true" category="domain" builtin="true" name="term/domain">
                                <default-value>undefined domain</default-value>
                            </field>
                            <field data-type="complex" builtin="true" name="term/msr"/>
                            <field data-type="uuid" builtin="true" name="term/uuid"/>
                            <field data-type="text" builtin="true" name="term/id"/>
                            <field data-type="text" builtin="true" name="term/frequency"/>
                            <field data-type="complex" builtin="true" name="term/variants-settings"/>
                            <field data-type="dateTime" builtin="true" name="term/creation-date-time"/>
                            <field data-type="text" builtin="true" name="term/creator-user-name"/>
                            <field data-type="dateTime" builtin="true" name="term/last-modification-date-time"/>
                            <field data-type="text" builtin="true" name="term/last-modifier"/>
                            <field data-type="complex" set-valued="true" builtin="true" name="term/event"/>
                            <field data-type="text" name="customer"/>
                            <field data-type="text" name="note"/>
                            <field data-type="list" category="process status" name="processStatus">
                                <default-value>unprocessed</default-value>
                            </field>
                            <field data-type="list" set-valued="true" category="color" name="color_ts">
                                <default-value>dark red</default-value>
                            </field>
                            <field data-type="list" category="term type" name="termType">
                                <default-value>undefined</default-value>
                            </field>
                            <field data-type="text" name="sourceOfTerm"/>
                            <field data-type="text" name="emma"/>
                            <field data-type="text" name="assignedTo"/>
                            <field data-type="html" name="context"/>
                            <field data-type="list" category="gender" name="gender">
                                <default-value>undefined</default-value>
                            </field>
                            <field data-type="text" name="project"/>
                            <field data-type="text" name="crossReference"/>
                            <field data-type="text" name="externalCrossReference"/>
                            <field data-type="text" name="geographicalUsage"/>
                            <field data-type="list" category="part of speech" name="partOfSpeech">
                                <default-value>undefined</default-value>
                            </field>
                        </term-level>
                    </fields>
                </schema>
            </actif>

## Filters [/iq/services/v9/rest/terminology/filters]

### Get available filters [GET]

Returns the ids/names of all filters for term search operations, that
are available to the user in the current session. The filters can be
referenced by their `id` in a search API operation, described in the
next section.

+ Request

    + Headers

            Authorization: session your_session_id

+ Response 200 (application/json)

    + Body

            {
                "user": "admin",
                "filters": [{
                    "id": "Preferred Technical Names"
                }, {
                    "id": "SEO"
                }, {
                    "id": "Images"
                }]
            }

## Search terms [/iq/services/v9/rest/terminology/searchTerms]

### by criteria [POST]

Terms can be searched by:

* term `name`, supporting `%` as wildcard;
* `language` id
* `domains` an array of one or several domain names
* `filter` id
* or any combination of the above

The individual fields of the search criteria need to be "escaped" by
their unicode positions in case they contain characters that would
otherwise break the JSON request string. For example, the
apostrophe/single quote character `'` is escaped as `\u0027`.

The search API supports pagination to retrieve only a certain subset
of the result set. The parameters are:

* `offset`, the index of the first term to display (starting from 0,
where the terms are always sorted ascending by their name)
* `limit`, the maximal number of terms to return, starting from
offset; if < 1, no limit is imposed.

The only supported media type for request as well as
result is application/json.

The search-terms service function requires a request object in the
format illustrated by the following example:

```
{
    "criteria": {
        "name": "d\\u00e9bit%",
        "language": "fr",
        "domains": ["Technical Names", "Demo"],
        "filter": "Preferred Technical Names"
    },
    "pagination": {
        "offset": 0,
        "limit": -1
    }
}
```

The `criteria` and `pagination` values are mandatory, as well as
`offset` and `limit`, but you can leave out (or set to `null`) those
fields of criteria that aren’t required by a specific query (for
domains you can also pass an empty array `[]`).

The criteria that exist in the search request are then combined by AND
(if domains contains more than one value, they're combined into a
domain filter by OR-ing them) in the resulting filter.

The response is a JSON object with the following attributes:

* `search` contains your search criteria and pagination settings; you
could reuse that object for subsequent calls with the same criteria
* `totalResultCount` is the total number of hits for the search,
before applying the pagination limit
* `terms`: an array of term objects, each containing the attributes
`name`, `status`, `domains`, `uuid` (the UUID of the term: use that
UUID to identify the specific term data from the full entry that you
retrieve by the entry UUID), `entry`; entry again is an object with
two attributes uuid and id, the UUID, and ID of the entry. Using the
entry UUID or ID you can then retrieve the entire entry via `GET
/entries` (see above).

If there are no matching terms (or you request
an offset greater than the result count), terms will be an empty
array. If your search request refers to a nonexistent filter, the
server will respond with a 400 (Bad Request).


+ Request

    + Header

            Authorization: session your_session_id

    + Attributes (SearchRequest)

    + Body

            {}

+ Response 200 (application/json)

    + Attributes (SearchResult)

    + Body

            {
                "terms": [{
                    "name": "debit d\u0027air repris",
                    "status": "preferred",
                    "domains": ["Technical_Names", "undefined domain"],
                    "uuid": "5334a674-848b-44a3-8b42-1756d38717ef",
                    "entry": {
                        "uuid": "a918fccf-4a94-4398-b260-4d792289952c",
                        "id": "13"
                    }
                }, {
                    "name": "debit d\u0027évacuation",
                    "status": "deprecated",
                    "domains": ["Technical_Names", "undefined domain"],
                    "uuid": "38e4ce12-4175-465e-a26f-4bb6d8a7ea15",
                    "entry": {
                        "uuid": "a918fccf-4a94-4398-b260-4d792289952c",
                        "id": "13"
                    }
                }],
                "search": {
                    "pagination": {
                        "offset": 0,
                        "limit": -1
                    },
                    "criteria": {
                        "name": "d%",
                        "language": "fr",
                        "filter": null,
                        "domains": ["undefined domain","Technical Names"]
                    }
                },
                "totalResultCount": 2
            }


## Find terms [/iq/services/v9/rest/terminology/findTerms/{sessionId}]

### by criteria [POST]

You can also search for terms using an older method called
`findTerms,` which supports some search criteria that aren't available
in the `searchTerms` method above, and which also returns the result
in a specified target format, just like get entries described above.

The following search criteria are supported:

* term `surface` (name), supporting `%` as wildcard
* `language` id
* `domain` - a single domain name
* `entry` ID/UUID - an array of entry IDs or entry UUIDs
* custom `criteria` - an array of `field=value` strings, where field
  is one of the following ACTIF field names:
  * `term/id`
  * `term/uuid`
  * `entry/id`
  * `entry/uuid`
  * `term/creation-date-time` (prepend with `<` or `>` to find terms
    created before or after the given date)
  * `term/last-modification-date-time` (prepend with `<` or `>` to
    find terms modified before or after the given date)
  * `term/creator-user-name`
  * `term/last-modifier`
  * any custom field name (as it appears in ACTIF)

The individual fields of the search criteria need to be "escaped" by
their unicode positions in case they contain characters that would
otherwise break the JSON request string. For example, the
apostrophe/single quote character `'` is escaped as `\u0027`.

All criteria are combined with AND when the term filter is
constructed. All criteria are optional; if you don’t give any
criteria, the result includes all terms.

The desired result format needs to be specified in the required format
attribute of the request object (not in the Accept HTTP header). The
supported media types are the same as for the "get entries" method
above:

* `application/vnd.acrolinx.actif+xml`: return terms as ACTIF in XML
* `application/vnd.acrolinx.mtf+xml`: return terms as SDL MultiTerm XML

Finally, you can optionally have the term base structure (schema)
included in the response by setting the `withSchema` attribute to
true.

+ Parameters

    + sessionId: `56429c06fbd5da74z` (string, required) - session ID

        The current session ID

+ Request

    + Attributes (FindTermsRequest)

    + Headers

            Content-Type: application/json

+ Response 200 (text/plain)

    + Body

            <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
            <actif xmlns="http://www.acrolinx.com" version="1.0">
                <origin date="2025-03-11T10:19:38.949Z"><tool/></origin>
                <data>
                    <source-languages><lang>en</lang></source-languages>
                    <entry>
                        <value field="subjectField">undefined</value>
                        <value field="entry/id">1307356662917</value>
                        <value field="entry/uuid">ff61f9ce-9c23-4874-bb98-cc58456b8734</value>
                        <head>
                            <term>
                                <name>2-Loch-Buchse</name>
                                <language>de</language>
                                <value field="term/status">preferred</value>
                                <value field="term/domain">ADSL</value>
                                <value field="term/uuid">6c2b681c-0d2f-4820-9833-8b2d35ab6fe8</value>
                                <value field="term/id">22946</value>
                                <value field="term/frequency">0</value>
                                <value field="term/creation-date-time">2011-06-06T10:37:42.963Z</value>
                                <value field="term/creator-user-name">admin</value>
                                <value field="term/last-modification-date-time">2024-06-26T14:38:51.282Z</value>
                                <value field="term/last-modifier">peter.bernds@acrolinx.com</value>
                                <value field="processStatus">finalized</value>
                                <value field="gender">undefined</value>
                                <value field="partOfSpeech">undefined</value>
                                <value field="termType">undefined</value>
                                <complex-value field="term/msr">
                                    <attribute name="analysisMode">base (analyzed)</attribute>
                                    <attribute name="token">2-Loch-Buchse</attribute>
                                    <attribute name="occurrence">1</attribute>
                                    <attribute name="mcat">noun</attribute>
                                </complex-value>
                                <complex-value field="term/event">
                                    <attribute name="user">peter.bernds@acrolinx.com</attribute>
                                    <attribute name="date">2024-06-25T13:51:47.671Z</attribute>
                                    <attribute name="type">COMMENT</attribute>
                                    <attribute name="text">Test</attribute>
                                </complex-value>
                            </term>
                        </head>
                    </entry>
                </data>
            </actif>

## Search entries [POST /iq/services/v9/rest/terminology/searchEntries]

You can retrieve all or only the entries (represented by their UUID
and ID) of specific domains by using the searchEntries service
endpoint. This service works similar to the "search terms" service,
but you can only specify a list of domains as search criterion, for
example:

```
{
    "criteria": {
        "domains": ["Technical_Names", "Demo"]
    }
}
```

Passing a nonempty array will get you all entries that contain at
least one term that is assigned to at least one of the specified
domains. Passing an empty array for domains will get you all entries.

The response is a JSON object with the following attributes:

* `search` contains your search criteria
* `totalResultCount` is the total number of entries matching the
  criterion
* `entries`: an array of entries, each containing the attributes `id`,
  and `uuid`. Using the entry UUID or ID you can then retrieve the
  entire entry via `GET /entries` (see above).

+ Request

    + Attributes (SearchEntriesRequest)

    + Headers

            Authorization: session <SESSION_ID>

    + Body

            {"criteria":{"domains":["undefined domain", "Technical_Names"]}}

+ Response 200 (application/json)

    + Attributes (SearchEntriesResult)

    + Body

            {
                "entries": [{
                    "uuid": "a918fccf-4a94-4398-b260-4d792289952c",
                    "id": "13"
                }, {
                    "uuid": "ee1c8221-5ac2-465a-bcb8-2f329ba0da8a",
                    "id": "1391421694240"
                }],
                "search": {
                    "criteria": {
                        "domains": ["undefined domain", "Technical_Names"]
                    }
                },
                "totalResultCount": 2
            }

## Deployment of Terminology [PUT /iq/services/v9/rest/terminology/deployTerminology]

After terms and entries have been created or updated using the above
method, they're not immediately available for checking. To make the
new or updated terms available for checking, the terminology needs to
be "deployed". Currently, triggering a "deploy" of the terminology
just causes all running language servers to reload their language
configuration, which includes the loading of the terminology. Please
note that a language becomes unavailable for checking for a certain
amount of time up to several minutes. Therefore terminology
deployments should be scheduled for convenient times and not just done
after each term or entry update.

You only need to (re)deploy terms/entries in domains and languages the
language configuration uses for checking. For instance, when you've
updated only the Arabic translation of a term, and there's no language
server running for Arabic, a "deploy" isn’t necessary.

+ Request

    + Headers

            Authorization: session <SESSION_ID>

+ Response 204

## Media files [/iq/services/v9/rest/terminology/media/{filename}]

### Upload [POST]

A multimedia object can be uploaded to the Core Platform specifying a
unique file name. We recommend using a scheme based on newly generated
UUIDs plus a readable part and the file extension. If an existing
filename is used, the old one will be replaced.

To transfer a media file to the Core Platform the term API service,
call POST on /media/{finaName}.

Supported media types are:

image/*: all images types, for example, image/png, image/gif, etc.
application/pdf
Required privileges:

Terminology - Import terms (implies "Edit terms")
Return codes:

201 (Created) in the case of success. The Location header contains the URL of the uploaded content.
404 (Not Found) if the filename contains a /.

+ Parameters

    + filename: `document.pdf` (string, required) - The filename to upload

+ Request

    + Headers

            Authorization: session <SESSION_ID>

+ Response 201

    + Headers

            Location: koko


### Download [GET]

A multimedia object that has been uploaded through this API can be
downloaded using the unique filename. To achieve this, call GET on
/media/{filename}.

Required privileges:

Terminology - Export terms (implies "Read terms")
Return codes:

In case of success, 200 (OK) and the response body contains the media file.
404 (Not Found) if the filename doesn't exist.

+ Parameters

    + filename: `document.pdf` (string, required) - The filename to download

+ Request

    + Headers

            Authorization: session <SESSION_ID>

+ Response 200