25.3.0 API Changelog

Breaking changes

Renaming "liveness" to KYC

We have decided to rename recenty introduced liveness detection params to KYC to better reflect their purpose as we expanded the functionality. Now KYC can be used on only for "liveness" detection but also for other types of checks. We support Identomat as our provider and now you can use more factors of KYC namely:

idVerification - The Identity Document step involves users scanning or uploading photos of their ID documents.
livenessDetection - The Liveness step verifies that the user is physically present by analyzing a live facial image or video.
selfieWithId - In the Selfie with ID step, users are required to hold their document in their hands so that both their face and the document are visible.

Affected endpoints:

GET /share/liveness/generate/{liveness_provider}
- path changed to: GET /share/kyc/generate/{kyc_provider}
- response param livenessToken changed to kycToken
- added two new fields to response verificationRemainingAttempts and verificationResetTime
GET /share/liveness/result
- path changed to: GET /share/kyc/result
- query param livenessToken changed to kycToken
POST /share
- renamed param data.livenessProviders => data.kycProviders
- added param data.kycFactors (see possible values above)

CODE

POST /share
{
  "id": "22250fcf-d04d-4751-a640-9dd48b6ce280",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "client@example.com",
      "kycProviders": ["identomat"],
      "kycFactors": ["livenessDetection"]
    }
  ],
  "signatureFields": [
    {
      "user": [
        "client@example.com"
      ],
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.5,
        "percentY": 0.1,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    }
  ]
}

Non-breaking changes

Added `fieldGroupId` and `lockRatio` to sign preparation endpoints

We have added possibility to merge group of sign fields to easy to use groups so multiple fields can be placed together. Also fields (signatures) now offer posibility to lock or unlock frame ratio.

Endpoints:

POST /share
POST /documents
PUT /documents/edit/{version}

Sharing and signing endpoints have optional param `useTsa`

Endpoints:

POST /share
PUT /documents/sign/{version}

To use this feature you have to have right set_tsa and TSA needs to be confiugured in settings to value other than NONE. If you then share document for signature with this flag all signatures will include TSA timestamp.

Added LLM verification endpoint

We have added endpoint POST /settings/verify/llm. When you want to point Circularo to your custom LLM or use your own API key, you can use this endpoint to test if it can be reached and if authentication works as expected.

Possibility to use drafts for external users

We have added option to use drafts for external users. Its mainly intended to keep saved progress when filling large forms. New endpoints are:

POST /share/draft
GET /share/draft

Possibility to upload attachments for external users

We have added possibility for external users to upload attachments to a shared document. Document must be shared for action (not a view share) and it must be allowed by specifying uploadAttachment right while sharing document. All current attachments limits for attachment count and size still apply.

New/updated endpoints:

PUT /share/document/sign/{version} - added attachments to body to provide array of file IDs to add
PUT /share/document/sign/{version} - added attachments to body to provide array of file IDs to add
POST /share/upload/attachment - new endpoint for actually uploading file and receiving its ID