24.1.0 API Changelog

Breaking changes

Removed endpoints

GET /documents/info/allCount.
DELETE /documents/:id/:version.

Renaming team to organization

In various entities within Circularo (e.g., documents, users, groups), the team property has been renamed to organization across the system.

For example, properties that were previously named allowedForTeam are now called allowedForOrganization.

Ensure that any integrations or API calls referencing the old team property are updated accordingly to reflect this change.

Affected requests

GET /acls/{id} - allowedForTeam => allowedForOrganization
PUT /acls/{id} - allowedForTeam => allowedForOrganization
POST /groups - team=> organization
POST /rights - allowedForTeam => allowedForOrganization
PUT /rights/{id} - allowedForTeam => allowedForOrganization
PUT /users/{id} - team=> organization
POST /users - team=> organization
POST /users/register - teamName => organizationName
GET /webhooks - teams => organizations

Affected responses

GET /files/capacity - teamLimit=>organizationLimit; teamUsed=>organizationUsed
POST /files/saveFile - teamLimit=>organizationLimit; teamUsed=>organizationUsed
PUT /files/updateFile/hash/{hash} - teamLimit=>organizationLimit; teamUsed=>organizationUsed
POST /login - isTeamAdmin=> isOrganizationAdmin; teamGroup=> organizationGroup; team => organization
GET /login - isTeamAdmin=> isOrganizationAdmin; teamGroup=> organizationGroup; team => organization
PUT /users/activate - isTeamAdmin=> isOrganizationAdmin; teamGroup=> organizationGroup; team => organization
GET /users/activation - team => organization
GET /users/search - team => organization

Licenses changed to subscriptions

In this release, the term license has been replaced with subscription. This is a significant change that includes the addition of new endpoints and the removal of some existing ones.

This section covers only modifications to existing endpoints that are not directly related to subscriptions. All new subscription-related endpoints will be documented separately.

Affected requests

POST /groups/search - includeLicenseInfo => includeSubscriptionInfo
POST /groups/{id} - license=> subscription

Affected responses

POST /groups/search - licenseObj=> subscriptionObj
POST /login - license=> subscription
GET /login - license=> subscription
PUT /users/activate - license => subscription

Standalone timestamp for documents

The seal endpoint has been extended to allow adding a standalone timestamp to a document. This means you can now add not only a certificate but also a standalone TSA timestamp (if configured).

Updated Endpoint

PUT /documents/seal/{version}

New Request Body Parameters

At least one of the following parameters must be set to true:

certificate – Specifies whether the document should be sealed with a certificate.
timestamp – Specifies whether a standalone timestamp should be added.

Non-breaking changes

PDF/A Conversion Option for File Uploads

A new PDF/A conversion option has been added when uploading files or creating documents. You can now specify whether a file should be converted to PDF/A format.

Affected Requests

The following endpoints now support the usePdfA parameter (true/false):

POST /documents/bulk/create
POST /documents
POST /documents/{id}/convert
POST /files/saveFile
PUT /files/updateFile/hash/{hash}
POST /files/convert
POST /files/join

Ensure that your API requests include the usePdfA parameter if PDF/A conversion is required.

Dashboard Filtering Support

The POST /search/dashboards endpoint now supports filtering dashboards using an array of restrictions. These restrictions are raw Elasticsearch filters, allowing more granular control over dashboard execution.

Sample request:

CODE

POST /search/dashboards
{
  "dashboards": [{
    "name": "my_dashboard"
  }],
  "restrictions": [{
    "range": {
      "createDate": {
        "gte": "now-1y"
      }
    }
  }]
}

In this example, the stored dashboard will only execute on documents created in the last year.

For more details on filter formatting, refer to the Elasticsearch documentation.

Reports endpoint

A new endpoint, POST /search/reports, has been added. This endpoint returns a simplified version of documents with more easily parsable data, making it easier to process and analyze reports.

Sample request:

CODE

POST /search/report
{
  "fields": [],    //you can specify array of property names you need (e.g. only documentId and transactionEndReason)
  "query": {
    "size": 100
  }
}

Sample response:

CODE

{
  "from": 0,
  "total": 1,
  "results": [
    {
      "documentTitle": "prazdny.pdf",
      "documentId": "bf92bbcd-bbcb-4d6a-8d0e-6bf3867962de",
      "createName": "admin@circularo.com",
      "createDate": "2025-02-18T09:23:57.263Z",
      "totalRecipients": 1,
      "totalWaitingFor": 0,
      "totalProcessed": 1,
      "totalActions": 1,
      "uniqueProcessedParticipants": 1,
      "waitingFor": [],
      "alreadyProcessed": [
        {
          "shareId": null,
          "user": "admin@circularo.com",
          "shareType": "sign",
          "selfSign": true,
          "lastAction": true,
          "delegatedUser": false,
          "dateOfReceivingTheAction": "2025-02-18T09:24:46.883Z",
          "date": "2025-02-18T09:24:46.883Z",
          "verification": null,
          "duration": 0,
          "rights": null,
          "expiration": null,
          "reminder": null,
          "seen": true,
          "order": null
        }
      ],
      "waitingForTurn": [],
      "unused": [],
      "delegations": [],
      "shareStateName": "completed",
      "sharedWith": [],
      "sender": null,
      "transactionStartDate": "2025-02-18T09:24:46.883Z",
      "transactionEndDate": "2025-02-18T09:24:46.883Z",
      "transactionEndReason": "share_actions_completed",
      "transactionDuration": 0,
      "rights": {
        "readUsers": [
          "admin@circularo.com"
        ],
        "editUsers": [
          "admin@circularo.com"
        ],
        "readGroups": [],
        "editGroups": []
      },
      "tags": [],
      "signingTemplate": null,
      "customMetadata": {}
    }
  ]
}

Possibility to change share recipient

The share recipient for actions (accept/approve/review/sign) can now be changed without creating a new transaction.

Configuration

This feature must be enabled in settings using the allowChangeShareRecipientCondition parameter. The setting supports the following levels:

never – The existing share cannot be reassigned.
notProcessedByAnyone – The share can be reassigned only if no action has been performed on the document.
notProcessedByCurrentToken – The share can be reassigned until the current user (token) has executed an action.

Endpoint

PUT /share/{shareId}/recipient

Only the share creator can reassign the recipient.

Login Token Connection Info

The login token now includes additional connection details, providing more context about the user's device and environment. The following properties have been added:

browser - The name of the web browser used.
browserVersion- The version of the browser.
os- The operating system of the device.
platform - The platform on which the browser is running.

Sample Response

When retrieving a login token, you will now receive extended connection information in the response:

CODE

{
    "browser": "Chrome",
    "browserVersion": "133.0.0.0",
    "ip": "109.81.86.95",
    "location": {
        "city": "Prague",
        "country": "Czechia",
        "countryCode": "CZ",
        "region": "Prague"
    },
    "os": "Windows 10.0",
    "platform": "Microsoft Windows",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36"
}