23.0.0 API Changelog

Breaking changes

Bulk endpoints limited

The following bulk endpoints now limit the maximum number of records that can be specified at once. The exact number for each endpoint can be found in the OpenAPI schema. If you need to specify more records then is the limit, please send them in multiple requests, one after another, always after the previous one has completed.

CODE

PUT /contacts
PUT /contacts/share
DELETE /documents
POST /documents/{id}/checkRights
POST /documents/mget
POST /documents/untrash
PUT /documents/read
PUT /documents/star
PUT /documents/subscribe
PUT /documents/unread
PUT /documents/unstar
DELETE /drafts/bulk
PUT /enums/{name}/record
PUT /enums/{name}/record/share
PUT /folders/move
PUT /folders/relocate
POST /settings/emails/example
PUT /share
PUT /share/disable
POST /tags/modify/document
POST /tags/set/document
PUT /templates
PUT /templates/share
POST /users
PUT /users

Groups

Group object

As new roles become available in Circularo we decided to change way how we store role groups in teams. Until now only admin and user roles existed. But now there are three new roles (prepare, read, sign) so they are now stored in teamGroups object so they are more separated we may add some more in future. We also added property edition which is based on your subscription.

CODE

{
	"displayName": [{
		"language": "en",
		"value": "A-Team"
	}],
	"edition": "pro",
	"license": "dLRU2YkBmWCkDUT-Z_-H",
	"name": "c19c186a-0252-46ac-88b5-c5862ca70f9a",
	"team": "c19c186a-0252-46ac-88b5-c5862ca70f9a",
	"teamGroups": {
		"admin": "6aaa6d6c-af28-42c5-8542-95bfca081dff",
		"prepare": "e5717ec7-7a04-47be-9d83-718f9a99bee4",
		"read": "df1f2e35-77d4-4334-9809-abbc754c1f8d",
		"sign": "38c042a5-12fd-47fa-b934-ef6c1573531b",
		"user": "26388cc2-df38-4014-a3cf-31d545378e32"
	},
	"type": [
		"team"
	]
}

Users

Minimal user object

When user info is received minimal format e.g. when searching users, receiving users when searching documents there used to be field type its now replaced with recordType example:

CODE

[{
		"fullname": "John",
		"image": null,
		"mail": "john@example.com",
		"recordType": "external",
		"phone": "987654321"
	},
	{
		"fullname": "Teddy",
		"image": null,
		"mail": "john@example.com",
		"recordType": "internal",
		"phone": "123456789"
	}
]

Documents

Signing

You need to have use_sign right to sign documents. Also users to whom you are sharing for signature must have the same right. This check was added so you cant share document to user who is then unable to sign.

Limits

We have introduced new limits in Circularo. Signature fields already had some limits (refer to 22.1.0) we have added new limit for real signatures per user (10). When using real signatures, there may not be more than 10 of these per document per user. In this case its counted even if its multipage, meaning 1 signature on 11+ pages will throw error.

Signature fields

Signature field formats were made the same in documents, drafts and templates. You can use signature fields from template directly in share requests now. Sign field properties with types:

CODE

{
  "align": "string",
  "backgroundColor": "string",
  "bold": "boolean",
  "color": "string",
  "config": "string"  //stringified JSON
  "font": "string",
  "fontSize": "number",
  "groupId": "integer",
  "id": "string",
  "link": "string",
  "maxCharacters": "interger",
  "multipage": "boolean",
  "numberOfLines": "integer",
  "order": "integer",
  "pages": "Array<integer>",
  "position": {
    "percentX": "number",
    "percentY": "number",
    "percentWidth": "number",
    "percentHeight": "number"
  },
  "required": "boolean",
  "subtype": "string",
  "text": "string",
  "timestamp": "boolean",
  "tooltip": "string",
  "type": "string",
  "user": "Array<string>",
  "userRoleId": "integer",
  "userRoleName": "string",
  "values": "Array<string>"
}

Also documents include some “extra” properties that are related to sign field life cycle these properties are:

CODE

{
  "cancelled": "boolean",
  "filled": "boolean",
  "shareId": "string",
  "usage": "string"
}

These do not make sense to be put in templates but make sense only for documents.

Values - Dropdowns

Values of single options were moved from stringified JSON to separated values property as Array of strings.

GroupID - Radios

GroupId value for radio buttons was moved from config to root.

Templates/drafts specific changes

CODE

deleted decorationType
deleted url
deleted time
deleted pagesCount
deleted entity
deleted entityId
deleted editable
deleted stranger
deleted editableText

customId => config.customId
onBehalf => config.onBehalf
nonRemovableDocId => config.nonRemovableDocId
blob => config.hash
signOnBehalfOf => config.signOnBehalfOf
multipageType => config.multipageType
multipageCustom => config.multipageCustom
annotationText => config.unwrappedText
config.drawData = [{ drawingType, points, fill, strength }]
placeholder => config.placeholder
numberOfLines => config.numberOfLines

values = config.values ?? values
groupId = config?.groupId ?? groupId
numberOfLines = config?.numberOfLines ?? numberOfLines;  //if value was "auto" now it is -1
page => pages //now its Array
user //now its just array of strings (usernames/emails) not objects
wacomColor => color //only if wacom signature/initials field
signFieldId => id
annotationTextWrapped => text
options => values

All property config contains stringified JSON.

Settings

Filtering

When user requested settings object (or on login) Circularo used to send whole settings object event if not all settings were needed. We implemented static filtering and there are three possible filters. You are not required to do anything (except if you want all settings). Properties you receive in settings:

a) not logged user + external shares

CODE

"allowPasswordChange",
"allowedSignatureInputTypes",
"annotationDefaults",
"appName",
"dateFormat",
"defaultPreviewZoom",
"defaultStates",
"disableInvitationEmails",
"docIdPrefix",
"enableOtherSignFields",
"enableSignDrawing",
"enableWacomDriverCheck",
"externalFaqUrl",
"firstDayOfWeek",
"hidePasswordLogin",
"images",
"intros",
"language",
"minimumPasswordStrength",
"mobileSkin",
"navigationOrder",
"pdfjsPrintResolution",
"platformName",
"registration",
"shareAsideDetailConfig",
"signatureEnvelope",
"signatureProvider",
"skinData",
"telephone",
"termsAndConditions",
"timeFormat",
"url",
"wopi"

b) logged user

CODE

"advancedSearch",
"allSignersByDefault",
"allowedCloudProviders",
"allowedStatistics",
"allowedTemplateDefinitions",
"asideDetailAlwaysOpenInfo",
"asideDetailConfig",
"asideDetailFullEdit",
"auditTrailDetails",
"automaticReminders",
"backgroundThreshold",
"buttonCloud",
"charts",
"composeClone",
"composeHub",
"composeMergeFilesByDefault",
"composeTemplateSelection",
"defaultDefinitions",
"defaultShareRights",
"detectSignFields",
"disabledPreferenceProps",
"docIdIncluded",
"dropZoneMaxSize",
"dynamicTable",
"excludeActionIds",
"excludeHistoryActionIds",
"excludeUserActionIds",
"fastCompose",
"fixedFilters",
"imageSignature",
"inboxPostActionBehavior",
"instantPreview",
"landingPage",
"landingPageMobile",
"mobileDefaultHome",
"mobileDetailView",
"mobileDynamicTable",
"mobileNavigationOrder",
"navigationGroups",
"requireMFA",
"sendMetadataInShare",
"sequentialSignByDefault",
"sequentialSignChangeable",
"shareAfterCompleted",
"shareExpirationChangeable",
"shareExpirationDefault",
"signAutoFinish",
"signAutoStart",
"signPrepareTypes",
"skipSignTypeSelection",
"statistics",
"team",
"translationNamespaces",
"userStaticCustomFields",
"wopiCollaboration"

c) all setting - All settings can only be seen by super admins and organization admins in GET /settings/default and GET /settings/{type} when query parameter filter is passed with value all.

When user is logged it receives both not logged and logged properties.

Team

Changed format of team registration/creation settings. It now looks like this:

CODE

{
	"data": {
		"team": {
			"defaultEdition": "pro",
			"editions": [{
				"name": "pro",
				"roles": {
					"admin": {
						"acls": [
							"pro_admin",
							"pro_user"
						],
						"settings": null
					},
					"prepare": {
						"acls": [
							"pro_lite_user",
							"pro_prepare_only_lite_user"
						],
						"settings": "stringifed role settings"
					},
					"read": {
						"acls": [
							"pro_lite_user",
							"pro_read_only_lite_user"
						],
						"settings": "stringifed role settings"
					},
					"sign": {
						"acls": [
							"pro_lite_user",
							"pro_sign_only_lite_user"
						],
						"settings": "stringifed role settings"
					},
					"user": {
						"acls": [
							"pro_user"
						],
						"settings": null
					}
				}
			}],
			"enabled": false
		}
	}
}

Here you can find default ACLs for each role and list of editions. Only super admin can make any changes to this settings.

Templates

Sign entities

Replaced field signUsers with new field signEntities to better reflect than not only users may be defined there. Also its no longer a stringified JSON but rather an array of objects. Format with types:

CODE

{
  "signEntities": [
    {
      "type": "string",
      "users": [
        {
          "mail": "string",
          "contactType": "string",
          "fullname": "string",
          "language": "string"
        }
      ],
      "quorum": "integer",
      "userRoleId": "integer",
      "userRoleName": "string",
      "shareType": "string",
      "order": "integer",
      "shareRights": "Array<string>"
    }
  ] 
}

Sign fields

Already mentioned in chapter Documents > Signature Fields.

Fields

Property fields used to be stringified array of strings, it is now just array of strings, no stringification.

Exports

When exporting enums/contacts/templates, there is now size limit for JSON export. Which is same as max file upload size (settings.data.dropZoneMaxSize). This is because if you then try to re-import that file it would fail due to size. Try to do your exports in smaller batches.

Non-Breaking changes

Settings

Omit the sender’s name in the e-mail header

Some e-mail notifications include sender’s full name in the from header of the e-mail, like this Olive Yuw via Circularo <noreply@circularo.com>. You can remove the <SenderName> via part by setting a new boolean property omitSenderInEmail to true. Configurable on tenant and team (organization) level.

Disable option to change the property `sequential` when sharing a document to be signed

We added new property sequentialSignChangeable (defaults true) configurable on tenant and team (organization) level.

If this setting is disabled, share sign property sequential must be the same as in the document source template (in case the template ID has been specified during the document creation and the template exists and specifies the property sequential) or the same as the setting’s property sequentialSignByDefault.

Affects endpoint POST /share.

Default for “All signers“

We added new boolean property allSignersByDefault (defaults false) configurable on tenant and team (organization) level. If this setting is enabled, “All signers“ in a signing group is enabled by default.

This only affects default value when creating a signing process on front-end.

Allowed cloud providers

We added property allowedCloudProviders specifying list of allowed cloud providers configurable on tenant and team (organization) level. Possible values are ['googleDrive', 'oneDrive', 'dropbox', 'sharepoint'].

Allowed create signature types

We added string array property allowedSignatureInputTypes configurable on tenant and team (organization) level. This specifies list of ways user can create its signature on front-end. Possible values are ['draw', 'type', 'upload', 'wacom'].

Disable edit on user profile data

We added string array property disabledPreferenceProps configurable on tenant and team (organization) level. Items listed in this array cannot be changed in user profile. Possible values are ['phone', 'fullname', 'mail', 'company', 'role', 'photo'].

Disable changing expiration

We added new property shareExpirationChangeable(defaults true) configurable on tenant and team (organization) level.

If this setting is disabled, expiration wont be changeable on front-end when creating share process.

Expiration default value

We added new property shareExpirationDefaultconfigurable on tenant and team (organization) level. This property contains a string JSON witch can contain one of these formats {“type”: “time_span_span”, “timeSize”: {“span”: number, “size”: “year” | “quarter” | “month” | “week” | “day” | “hour”}} or {“type”: “time_span_time”, “exactTime”: “2023-08-09T11:50:21.392Z”}.

This property specifies default relative or exact time of share process expiration.

Allowed types for share progress

We added string array property disabledPreferenceProps configurable on tenant and team (organization) level. Items in this array specifies witch share types will be available when creating share process on front-end. Possible values are ['me', 'we', 'others', 'in_person', 'template'].

Translations

Fallback language for translations

The endpoint /languages/{lang}/translations/values/simple now accepts the new query parameter allowFallbackLanguage (defaults true). If it is enabled and some translations are missing in the requested language, translations from the tenant’s default language are used in their place.

Templates

More properties in template

There are now more properties that can be saved to template.

CODE

{
    expirationTime: EntityTemplatesTimeSpan;
    remindersStartDays: EntityTemplatesTimeSpan;
    remindersIntervalDays: integer;
    signatureType: "string"; // "image" or "signature";
    message: "string";
}

Where EntityTemplatesTimeSpan has following structure:

CODE

{
  type: "string", // "time_span_time" or "time_span_span"
  exactTime: Date,
  timeSize: {
    size: "string",
    span: integer
  }
}

Lock template

Templates can now be marked as locked via isLocked boolean property. When template is marked as locked and it is used in share process its ID should be send in the share request as described in Share based on template section.

Force template usage

If you want to be sure that all (required) fields from template are present in shared document, you can provide template ID in POST /share request. That way Circularo ensures that none of specified values from template has changed. You can still change/specify values that are not present in template.

Comb type field

We added new type of annotation field by adding property maxCharacters to annotation. You can specify how many characters should be allowed in that particular field and it will be divided into that many blocks. This is useful for field such as dates, social security numbers, or bank detail. Anywhere where you have prepared “boxes” to be filled. Example of annotation defined for maximum of 5 characters:

CODE

{
    "position": {
		"percentX": 0.1,
		"percentY": 0.1,
		"percentWidth": 0.1,
		"percentHeight": 0.013873474559446661
	},
	"pages": [1],
	"text": "12345",
	"color": "000000FF",
	"align": "left",
	"fontSize": 10,
	"backgroundColor": "FFFFFF00",
	"subtype": "annotation_generic",
	"maxCharacters": 5
}

Sign field IDs

Because of the locking templates, Circularo need unique IDs for sign fields in templates. You can either specify it yourself (it can be any unique string) or let Circularo generate it for you. If left empty or duplicate value found it will automatically be overwritten no error will be thrown.

Documents

Removing certificates

Added possibility to remove (external) certificates from document in PUT /documents/annotate/{version} endpoint. This can be achieved using new removeCerts body parameter.

Signature type

Document now contains property signatureType which defines “how” document will be signed. There are two possible values:

image - Signatures are embedded as images and then document is sealed after each signature. Only one seal is in actual document even if there are many individual signatures.
signature - Each individual signature is its own PDF signature field with certificate. That means that there can be individual certificate for each signer and they all remain in document.

Signature type cannot be changed once set for document.

Files

Signature anchors

When you are uploading or converting file using any of following endpoints:

CODE

POST /files/convert
POST /files/saveFile
PUT /files/updateFile/hash/{hash}

You can specify text/regexp to be searched in file. This work only for documents that are not scanned (text from them can be simply copied without OCR).

CODE

POST /files/saveFile?token=:authenticationToken

{
    "fileName": "Company Memorandum",
    "file": blob, //File blob
    "signatureAnchors":[{
      "id": "prepared_by",
      "offset": {
         "percentHeight": 0.07,
         "percentWidth": 0.25,
         "percentX": 0.28,
         "percentY": 0.08
      },
      "text": "PREPARED BY:"
    }]
}

Example of request that will search document for text “PREPARED BY:”. In response it will return positions for newly created text fields. Detailed info can be found here.

Organizations

Lite users

There are 3 new user roles in Circularo.

view only
prepare only
sign only

These users have different ACLs (rights) according to settings. You can assign new/existing users to these roles same way how you now assign admins/users.

Edition

Group object now contains edition property. This property can (currently) have values pro or business. By changing this value (only super admin can do that) all role groups get their ACLs changed according to settings.

Licenses

New limits

Added new limits to licenses that you should check before making related requests (otherwise you may be getting some errors). These limits are based on your subscription and you may not be limited by them.

liteUsers - maximum number of lite user (prepare + sign + view) allowed in organization
sealingTransactions - Sealing transaction are now counted separately from signing transactions, this contains total limit for organization.
sealingTransactionsPerUser - Same as sealing transactions but user based e.g. each user is only allowed to seal 10 documents, but organization has limit for 1000 seals. This is here when you want to make sure one user doesn’t consume all your transactions.

Users

Creator

If user was created using POST /users endpoint it now contains username of user who created it in property creator.

Forcing template

When you provide templateId in POST /share endpoint then Circularo will compare all fields you send in request and it will validate them against fields specified in that template. In share request you are free to fill any unspecified values, for example if there is no font size specified in template field you can set it to whatever you want. But you can’t change any specified values and they must be send in request in same format as they are in template. Take this partial example:

CODE

{
    ...
	"signEntities": [{
		"type": "user",
		"users": [],
		"quorum": 1,
		"userRoleId": 0,
		"userRoleName": "Recipient 1",
		"shareType": "sign",
		"order": 1
	}],
	"signFields": [{
			"bold": false,
			"config": "{\"multipageType\":\"all\",\"multiPageCustom\":\"1\",\"group\":false}",
			"id": "GfC0aRvWvMXeR0NO",
			"multipage": false,
			"order": 1,
			"pages": [
				1
			],
			"position": {
				"percentHeight": 0.1,
				"percentWidth": 0.39113986323861544,
				"percentX": 0.1,
				"percentY": 0.1
			},
			"required": false,
			"timestamp": false,
			"type": "signature",
			"user": [],
			"userRoleId": 0,
			"userRoleName": "Recipient 1"
		},
		{
			"align": "left",
			"backgroundColor": "#FFFFFF00",
			"bold": false,
			"color": "#000000",
			"config": "{\"multipageType\":\"all\",\"multiPageCustom\":\"1\",\"placeholder\":\"Text\",\"group\":false}",
			"font": "default",
			"fontSize": 10,
			"id": "wBVFBunaKqlGulsM",
			"multipage": false,
			"numberOfLines": -1,
			"order": 1,
			"pages": [
				1
			],
			"position": {
				"percentHeight": 0.01595449574336366,
				"percentWidth": 0.1,
				"percentX": 0.1,
				"percentY": 0.21000000000000002
			},
			"required": false,
			"subtype": "annotation_generic",
			"timestamp": false,
			"type": "annotation",
			"user": [],
			"userRoleId": 0,
			"userRoleName": "Recipient 1"
		}
	]
    ...
}

This is template that you want share to “force” on users. Share request will look like this:

CODE

{
	"objectType": "document",
	"id": "418875b5-38b5-4794-8d3c-ccc30461d9c1",      //id of document you want to share
	"type": "d_default",
    "data": [{
		"sharePurpose": "sign",
		"shareTo": "signer@circularo.com",	
		"rights": ["print"],
		"language": "en"
	}],
	"force": false,
	"sequential": false,
	"signatureType": "image",
	"templateId": "fda2f4d2-0727-4b19-a62c-fd5b33f210a9",   //template ID <= important
	"signatures": [],
	"annotations": [],
	"images": [],
	"signatureFields": [{
		"type": "signature",
		"pages": [1],
		"multipage": false,
		"position": {
			"percentHeight": 0.1,
			"percentWidth": 0.39113986323861544,
			"percentX": 0.1,
			"percentY": 0.1
		},
		"config": "{\"multipageType\":\"all\",\"multiPageCustom\":\"1\",\"group\":false}",
		"required": false,
		"order": 1,
	    "id": "GfC0aRvWvMXeR0NO",
		"user": ["signer@circularo.com"],
		"userRoleId": 0,
		"userRoleName": "Recipient 1",
		"timestamp": false,
		"bold": false
	}, {
		"type": "annotation",
		"subtype": "annotation_generic",
		"pages": [1],
		"multipage": false,
		"position": {
			"percentHeight": 0.01595449574336366,
			"percentWidth": 0.1,
			"percentX": 0.1,
			"percentY": 0.21000000000000002
		},
		"backgroundColor": "#FFFFFF00",
		"config": "{\"multipageType\":\"all\",\"multiPageCustom\":\"1\",\"placeholder\":\"Text\",\"group\":false}",
		"required": false,
		"order": 1,
		"id": "wBVFBunaKqlGulsM",
		"user": ["signer@circularo.com"],
		"userRoleId": 0,
		"userRoleName": "Recipient 1",
	    "align": "left",
		"bold": false,
		"font": "default",
		"fontSize": 10,
		"color": "#000000",
		"numberOfLines": -1,
		"timestamp": false
	}]
}

Signature rights

Rights use_workflow_sign, use_ad_hoc_sign, use_ad_hoc_share_sign a use_share_sign ware replaced by use_sign. User with this right can sign the document. It is also necessary for "in person" signing. This right can also be used to filter users in user search that cannot be recipients of signing process (sign/accept/approve/review).

New right use_prepare was created that allows user to prepare signing process for other users. It is also necessary to create/edit and use sign templates.

Breaking changes

Bulk endpoints limited

Groups

Group object

Users

Minimal user object

Documents

Signing

Limits

Signature fields

Values - Dropdowns

GroupID - Radios

Templates/drafts specific changes

Settings

Filtering

Team

Templates

Sign entities

Sign fields

Fields

Exports

Non-Breaking changes

Settings

Omit the sender’s name in the e-mail header

Disable option to change the property sequential when sharing a document to be signed

Default for “All signers“

Allowed cloud providers

Allowed create signature types

Disable edit on user profile data

Disable changing expiration

Expiration default value

Allowed types for share progress

Translations

Fallback language for translations

Templates

More properties in template

Lock template

Force template usage

Comb type field

Sign field IDs

Documents

Removing certificates

Signature type

Files

Signature anchors

Organizations

Lite users

Edition

Licenses

New limits

Users

Creator

Sharing

Forcing template

Signature rights

Disable option to change the property `sequential` when sharing a document to be signed