API docs by Redocly

Web Trust (1.57.0)

Download OpenAPI specification:Download

API Support: support@kopjra.com URL: https://webtrust.kopjra.com

Welcome to the Web Trust (WT) API documentation.

The versioning schema of these APIs is Semver-friendly.

Take a look at our knowledge base for more details regarding the API usage, examples and more.

Introduction

Web Trust (WT) is a suite of API solutions for electronically signing documents, webpages, and data flows. The main scope of most of the solutions is to sign an interaction between two parties over the Internet using a proprietary and patented technology. Web Trust’s solutions cover six possible workflows respectively, each of which could be integrated into a company process:

  • Document Advanced: API solution to fill-in and sign any PDF document such as policies and contracts using an Advanced Electronic Signature (AES). It identifies the signer using SPID (Sistema Pubblico di Identità Digitale).
  • Document Simple Forensic: API solution to fill-in and sign any PDF document such as policies and contracts. It identifies the signer using an OTP (One Time Password) via SMS. Each signature interaction takes place within an isolated environment that acquires it forensically using a patented methodology owned by Kopjra.
  • Document Simple: API solution to fill-in and sign any PDF document such as policies and contracts.
  • Webpage Forensic: API solution to apply a click-to-sign electronic signature on a note, policy or contract published on a webpage. Each signature interaction takes place within an isolated environment that acquires it forensically using a patented methodology owned by Kopjra.
  • Data Forensic: API solution to electronically sign data flows coming from application and/or IoT (Internet of Things) devices. Each signature interaction takes place within an isolated environment that acquires it forensically using a patented methodology owned by Kopjra.
  • Timestamp: API solution to apply qualified or trustless timestamps to documents or log files. With trustless we intend the notarization over the Bitcoin blockchain.

Endpoints

WT offers a set of endpoints that allow you to interact with the system. These endpoints are hosted at the following URL: https://api.webtrust.kopjra.com/v1. The following documentation will guide you through the available endpoints and their functionalities.

Preceding a manual activation on our part the user may also have access to a DEMO environment hosted at https://api-demo.webtrust.kopjra.com. This environment is a mirror of the production one and it is meant to be used for testing purposes only. The data stored in the DEMO environment is not guaranteed to be persistent. DEMO is not activated by default, if you need access to it please contact our support team.

Authentication

WT offers http basic authentication to allow access to its API. You can register new WT credentials at our developer portal. WT expects for the credentials to be included in all API requests to the server in a header Authorization.

http_basic_schema

Using HTTP Basic authentication, the user authenticates to WT by providing a credential string within the Authorization header. This credential string is encoded using base64 and consists of the id and secret, generated at our developer portal, separated by :.

For example, if the id is my_id and the secret is my_secret, the credential string would be my_id:my_secret and the base64 encoding would be bXlfaWQ6bXlfc2VjcmV0. Therefore the header would be: 

  Authorization: Basic bXlfaWQ6bXlfc2VjcmV0

Note that using curl or one of our clients you don't have to transform to base64 by yourself. It is enough to specify id:secret.

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Impersonators

Some special users will have the capacity to perform certain API calls as if they were made by another user, thus impersonating that other user. The impersonation capacity is rather powerful and it is given only to certain users directly by the system administrators. From now on we will call the user that is trying to impersonate another, the impersonator. Impersonation takes place when the API call contains the following header (besides the Authorization one):

X-Impersonate-User: <externalUserId>

With the concept of impersonation the user can be distributed into two (not necessarily) exclusive layers: the users that can be impersonated and the users that can impersonate other users (impersonators). An impersonator generally manages its own users and has a way to identify them in his/her own systems, this identification is what we called the externalUserId and it is the one that has to be provided when impersonating.

This impersonation header will instruct WT to:

  1. Verify whether externalUserId identifies a user that can be impersonated by the impersonator that is making the API call.
  2. If yes then proceed with the API call as the impersonated user

if there is no user corresponding to that externalUserId then the system will automatically create one and will link it to the impersonator.

archetypes

Archetypes describe the tags schema that a set of your interactions must adhere to, in order to be created. For example, if you want to split all of your interactions in 2 partitions (one for privacy policies and one for contracts), you can define two different archetypes. In the first one, you will specify all the meaningful tags for privacy policies (eg: an identifier of the signer and the version of your privacy policy) and in the second one you will specify all the meaningful tags for contracts (eg: an identifier of the signer, the version of the contract, and your company's associate that signed the contract on its behalf).

See our knowledge base for details regarding the API usage, examples and more.

Create an archetype

This API call allows you to create an archetype.

Authorizations:
http_basic_schema
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"
Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
required

Archetype creation object

name
string

The Archetype's given name

smsCustomMessage
string

Text to replace the default SMS message sent for OTP verification. Whithin this text we can use the placeholder {{CODE}} that will be replaced with the generated OTP code, in case the placeholder is not present, the OTP Code will be appended to the text.

fullNameSignatureFont
string
Deprecated
Default: "Caveat"
Enum: "Caveat" "LeagueScript" "MrsSaintDelafield" "ShadowsIntoLight" "SueEllenFrancisco" "AlexBrush" "Allura" "DancingScriptVariableFont" "Parisienne" "Stalemate"

Font to be used when signatureType is fullname_date, meaning that the signature will be generated automatically from signerFullname. This are the fonts available:

object

The customisations you applied to a Signature resource. Every field is optional.

object

Customisation of the email to be sent. If not specified, a default email will be used.

required
object

An object representing the tags to be added to the resource. Note: tag names can only contain US-ASCII letters and/or numbers. You can specify as many tag names as you like. In future you will be able to specify a regular expression to validate the tag value as well. For now, only null is accepted as value.

Responses

Request samples

Content type
application/json
{
  • "name": "Archetype 1",
  • "smsCustomMessage": "OTP: {{CODE}} - Enter the above code to sign your document",
  • "fullNameSignatureFont": "LeagueScript",
  • "signatureCustomisations": {
    },
  • "emailCustomisation": {},
  • "mandatoryTags": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Archetype 1",
  • "smsCustomMessage": "OTP: {{CODE}} - Enter the above code to sign your document",
  • "smsCustomMessageModeratedOn": null,
  • "fullNameSignatureFont": "LeagueScript",
  • "signatureCustomisations": {
    },
  • "emailCustomisation": {},
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "mandatoryTags": {
    }
}

Get all archetypes

You can use this endpoint to get all of your Archetypes.

Authorizations:
http_basic_schema
query Parameters
top
integer [ 1 .. 25 ]
Default: 5

The maximum number of object to be returned.

skip
integer >= 0
Default: 0

The number of results to be skipped starting from the first result. Used for pagination.

sortBy
string
Example: sortBy=name,-createdAt

A sorting criteria. It must be specified as comma separated list of terms, where each term can be: prop or +prop or -prop. The operator + or the absence of it indicates an ascending sorting direction, whereas the - operator indicates a descending sorting direction. prop can be one of the following:

  • id
  • name
  • createdAt
  • updatedAt

For example a valid sorting criteria specification would be:

sortBy=name,-createdAt

With this criteria you will get a list of interaction sorted by name and for each equal name then it will be sorted by createdAt in descending order.

Responses

Request samples 

curl "{SERVER}/archetypes"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

# TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
[
  • {
    }
]

Get an archetype by Id

This endpoint retrieves a specific archetype.

Authorizations:
http_basic_schema
path Parameters
archetypeId
required
number
Example: 85
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "{SERVER}/archetypes/85"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Archetype 1",
  • "smsCustomMessage": "OTP: {{CODE}} - Enter the above code to sign your document",
  • "smsCustomMessageModeratedOn": null,
  • "fullNameSignatureFont": "LeagueScript",
  • "signatureCustomisations": {
    },
  • "emailCustomisation": {},
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "mandatoryTags": {
    }
}

Deletes an archetype by Id

This endpoint deletes a specific archetype, if there is no interaction with this archetype.

Authorizations:
http_basic_schema
path Parameters
archetypeId
required
number
Example: 85
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl -XDELETE "{SERVER}/archetypes/85"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Archetype 1",
  • "smsCustomMessage": "OTP: {{CODE}} - Enter the above code to sign your document",
  • "smsCustomMessageModeratedOn": null,
  • "fullNameSignatureFont": "LeagueScript",
  • "signatureCustomisations": {
    },
  • "emailCustomisation": {},
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "mandatoryTags": {
    }
}

interactions

Webpage Forensic API

This solution offers an alternative to the "Document" ones, that allows a company to create interactions to apply click-to-sign electronic signatures. In this case the company may want to sign a contract or policy but in this case they won’t be within a PDF document but inside a web page.

See our knowledge base for details regarding the API usage, examples and more.

Data Forensic API

This solution allows a company to sign data flows coming from Single Page Applications (SPA), Native Applications or IoT (Internet of things) devices; also in this case the signatures happen within a forensic environment using a proprietary and patented methodology following the standard ISO/IEC 27037:2012. The key difference between this solution and the Webpage Forensic API is that in this case the context that produces the signature is not acquired forensically.

See our knowledge base for details regarding the API usage, examples and more.

Create an interaction

Before you can acquire an action done by one of the users (and its context), you need to create a new interaction, and redirect the user to the forward URL (fUrl) specifically provided by WT. You will find this fUrl inside the body of the response of this call.

At the end of this call, remember to redirect your user to fUrl!

Since we don't implement any of your backend business logic, the user's request needs eventually to be re-submitted to your web server. Therefore you must provide us with the oURL where the endpoint that receives the user request must reside.

This call supports two different variations: full or no_html. The first one corresponds to the case of Webpage Forensics API and the second one corresponds to the case of Data Forensics API.

If you use the full variation, you need to provide us with some HTML that will be the context on which the user is going to do his action. The user's action could be for instance a form submission (a POST or a GET) or the click on a link (only a GET). In both cases, you have to pre-render the HTML on your server and give it to us.

Within your pre-rendered HTML, remember to replace the URL where you originally intended to handle the user's action with the <%= e_url %> placeholder.

Otherwise, if you use the no_html variation, WT will just acquire the single action coming from the user to your service (MITM'ed by WT) with no information about its context. In this case, you will not have to provide us any pre-rendered HTML.

Moreover, it is possible to specify a Callback URL where WT will send a POST request at the end of the single interaction process, stating if everything went OK (in this case, the body of the POST request will include the body sent from the user to our system) or if an error occurred.

You can also specify to make WT act as a proxy (actAsProxy) to your service, which means that the latter interaction to the specified oURL will happen from our servers instead of from your customer's client. This has the only disadvantage that you cannot set a cookie to your customer's client, otherwise there is no reason to not use this, given that you will have improved security (eg: no risk that a rogue customer's client can block/amend the request that will be sent to your server).

Finally, you can also decide to put any tag on your interaction.

Future retrievals requests can only be done by matching interaction IDs or custom tags! Otherwise, we won't be able to fetch the data contained in your pre-rendered HTML or in the content submitted by your user's action.

Authorizations:
http_basic_schema
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"
Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
required

Interaction creation object

oURL
required
string

Original URL. The URL where the request was originally intended to go. At the end of the acquisition process, the user will automatically re-submit the request to this URL. The company's service must be ready to serve the user's request in this URL.

variation
string
Default: "full"
Enum: "full" "no_html"

The variation you want to use, depending on whether the interaction is intended for server-side rendered web pages or api call. Therefore indicates if the interaction will have context or not.

isForensic
boolean
Default: true

Sets whether the interaction is forensic or not. Interactions that are not forensics will provide less information inside the final XML packet, for instance it won't contain the PCAP and KEYS. Also for non-forensic interaction a dedicated environment won't be spawned.

actAsProxy
boolean
Default: false

If set to true, WT will act as a proxy to your service, shipping directly the final interaction to your oURL instead of your customer's client. This is recommended.

prerenderedHtml
string

The pre-prendered HTML to be displayed by WT's container web server. It must contain the string <%= e_url %> somewhere in it. It is mandatory if the variation is undefined or full.

archetypeId
integer >= 1

If the interation has an archetype, this field represents the archetypes's unique identifier.

extradata
string <= 262144 characters

It is a free text field that can be used to store any kind of information

object

An object representing the tags to be added to the Interaction. Note: tag names can only contain US-ASCII letters and/or numbers, whereas tag values can be any UTF-8 string. The key max length must be 100 and the value max length must be 255.

Responses

Request samples

Content type
application/json
{
  • "oURL": "http://company-url.service.com/",
  • "variation": "full",
  • "isForensic": true,
  • "actAsProxy": true,
  • "prerenderedHtml": "string",
  • "archetypeId": 85,
  • "extradata": "Extra data",
  • "tags": {
    }
}

Get all interactions

You can use this endpoint to get all of your Interactions. In the future, you will also be able to search among interactions using custom tags (still to be implemented).

This endpoint retrieves all of your interactions. Please note that the attached files are not shown here: they are shown on a single-interaction basis.

Authorizations:
http_basic_schema
query Parameters
top
integer [ 1 .. 25 ]
Default: 5

The maximum number of object to be returned.

skip
integer >= 0
Default: 0

The number of results to be skipped starting from the first result. Used for pagination.

emptyScope
boolean
Default: false

If true the DB queries will be optimized, but some of the attributes may not be returned. It is advised to use the GET by ID endpoint to retrieve the full object.

sortBy
string
Example: sortBy=oMethod,-createdAt

A sorting criteria. It must be specified as comma separated list of terms, where each term can be: prop or +prop or -prop. The operator + or the absence of it indicates an ascending sorting direction, whereas the - operator indicates a descending sorting direction. prop can be one of the following:

  • id
  • oURL
  • oMethod
  • variation
  • currentStatus
  • expiresAt
  • userLandedAt
  • userTookoffAt
  • archetypeId
  • createdAt
  • updatedAt

For example a valid sorting criteria specification would be:

sortBy=currentStatus,-createdAt

With this criteria you will get a list of interaction sorted by currentStatus and for each equal currentStatus then it will be sorted by createdAt in descending order.

oMethod
string
Enum: "get" "post" "patch" "put" "option" "delete"

The original method of the interaction.

variation
string
Enum: "full" "no_html"

The variation of the interaction.

currentStatus
string
Enum: "SUBSCRIBED" "POD_FAILED" "CONCLUDING" "CONCLUDED"

The current status of the interaction.

hasPrerenderedHtml
boolean
Example: hasPrerenderedHtml=true

Indicates whether the interaction contains the prerendered HTML show to the user or not.

createdAt
string
Example: createdAt=2018-02-01T12:34:23|2018-04-01T12:34:23

Range of timestamps with one of the following formats:

  • YYYY-MM-DDTHH:mm:ss|YYYY-MM-DDTHH:mm:ss = closed date range
  • |YYYY-MM-DDTHH:mm:ss = opened date range (no start date)
  • YYYY-MM-DDTHH:mm:ss = opened date range (no end date)
archetypeId
integer >= 1

Get the interactions corresponding to the specified archetype id.

tag:anyTagName
string
Example: tag:anyTagName=tagValue

You can filter your interactions by specifying a single tag:tagName=tagValue pair in the query. Notice the prefix tag: that needs to be prepended to the tag name that we want to use.

users
Array of strings
Example: users=externalUserId1,externalUserId2

Only if you are an admin, you can get all of the interactions belonging to your specified users

header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "https://api.webtrust.kopjra.com/v1/interactions"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

# TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
[
  • {
    }
]

Get an interaction by Id

This endpoint retrieves a specific interaction, including any tag and signed URLs that can be used to download any available attached file.

Authorizations:
http_basic_schema
path Parameters
interactionId
required
number
Example: 85
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "{SERVER}/interactions/85"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "id": 83,
  • "oURL": "http://company-url.service.com/",
  • "oMethod": "get",
  • "isForensic": true,
  • "actAsProxy": true,
  • "archetypeId": 85,
  • "hasPrerenderedHtml": true,
  • "expirationPeriod": 3600,
  • "expiresAt": "2018-02-14T14:25:57.000Z",
  • "deletedAt": "2018-02-14T14:25:57.000Z",
  • "deletedEvidence": true,
  • "userLandedAt": "2018-02-14T14:25:57.000Z",
  • "userTookoffAt": "2019-02-14T14:25:57.000Z",
  • "downloadableUntil": "2020-02-14T14:25:57.000Z",
  • "currentStatus": "CONCLUDED",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "tags": {
    },
  • "extradata": "Extra data",
  • "auditTrailXML": "<auditTrail>...</auditTrail>",
  • "auditTrail": {
    },
  • "attachedFiles": {}
}

Deletes an interaction by Id

This endpoint marks a specific interaction as deleted. It will delete all evidence if present and mark the interaction as deleted (setting a date)

Authorizations:
http_basic_schema
path Parameters
interactionId
required
number
Example: 85
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl -XDELETE "{SERVER}/interactions/85"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "error": "Internal Server Error",
  • "message": "An internal server error occurred"
}

signatures

Document Simple Forensic API

This solution allows us to create and manage Simple Electronic Signatures (SES) with a Forensic layer. With respect to a normal SES, by adding the proprietary and patented methodology that creates a forensic layer (following the standard ISO/IEC 27037:2012) WT offers a signature with a higher probatory value, positioning it between a SES and an AES. On top of that, in this signing process one can verify the identity of the signer by sending an OTP via SMS, adding more probative value. See our knowledge base for details regarding the API usage, examples and more.

Document Simple API

This solution is fairly similar to the Document Simple Forensic API. It provides a Simple Electronic Signature (SES) with an audit trail, but in this case there won’t be an OTP identification and the audit trail is not forensic.

See our knowledge base for details regarding the API usage, examples and more.

Create a signature

Creates a signature for the specified documents. The response will contain a link (fUrl) to the signature environment.

Authorizations:
http_basic_schema
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"
Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
required

Signature creation object

signerFullname
required
string

Full name of the signer

signatureType
required
string
Enum: "graphic" "fullname_date" "none"

Signature type can be a graphic stroke, an automatically generated text from the signer's fullname or nothing at all. This value defines what will be shown in the signature field inside the PDF.

forcedSignaturePNGBase64
string <byte>

PNG in base64 to be forced as signature when the signatureType is graphic. This PNG will be used instead of asking the signer for the graphic signature strokes. The PNG will be shown to the signer as a preview of the signature inside the signing environment.

isForensic
boolean
Default: true

Sets whether the interaction is forensic or not. Interactions that are not forensics will provide less information inside the final XML packet, for instance it won't contain the PCAP and KEYS. Also for non-forensic interaction a dedicated singing environment won't be spawned.

ignoreDownloadAll
boolean
Default: false

This field makes sense when we are signing multiple documents. There is a functionality inside the signing environment that allows the signer to download all the documents at once. If this property is true the signer won't be able to download all the documents at once, but only one by one.

pades
boolean
Default: false

If true all the signatures applied inside all the documents will be PAdES compliant.

Note: If the following conditions are not met when pades is set to true, the signature creation will fail with error 400 :

  • The signatureFieldsType inside each document must be set to signature.
  • The number of documents to be signed must be less or equal than 5.
  • If a document was already signed using PAdES then failSignature cannot be specified andcompile and markPages will be ignored.
locale
string
Enum: "it" "en" "fr" "es" "de"

Language to be used in the texts provided automatically in the signing environment. WARN! It is a responsibility of the caller to translate accordingly all other custom texts, like extraChecks, smsCustomMessage and all customization to the pages.

extradata
string <= 262144 characters

It is a free text field that can be used to store any kind of information. This field won't transit to the signing environment. It is useful to store information that may be related to the signature process and isn't small.

required
Array of objects [ 1 .. 50 ] items

The documents to be signed.

object

The OTP sending method to be used for the signature. At least one of the two methods must be specified. When both are specified, SMS will be used as the primary method and email as the secondary one, in case the phone number validation fails, due to not supported country code.

Array of objects >= 0 items

Additional checkboxes to be added into the form of the signing page, external to the PDF document to be signed.

archetypeId
integer >= 1

If the signature has an archetype, this field represents the archetype's unique identifier.

object

The customisations you applied to a Signature resource. Every field is optional.

immediatePDFViewMobile
boolean
Default: false

If true immediately shows the PDF in the signing environment. This option can be true only when the amount of document is 1

rejectable
boolean
Default: false

If true the interaction can be refused in the signing environment via a Refuse button under the main call to action. If the interaction is refused, the its status will be REJECTED

object

An object representing the tags to be added to the Interaction. Note: tag names can only contain US-ASCII letters and/or numbers, whereas tag values can be any UTF-8 string. The key max length must be 100 and the value max length must be 255.

Responses

Request samples

Content type
application/json
{
  • "signerFullname": "string",
  • "signatureType": "graphic",
  • "forcedSignaturePNGBase64": "JVBERi0xLjYNJeLjz9MNCjI0IDA",
  • "isForensic": true,
  • "ignoreDownloadAll": false,
  • "pades": false,
  • "locale": "it",
  • "extradata": "Extra data",
  • "documents": [
    ],
  • "otp": {
    },
  • "extraChecks": [
    ],
  • "archetypeId": 85,
  • "signatureCustomisations": {
    },
  • "immediatePDFViewMobile": true,
  • "rejectable": true,
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "id": 83,
  • "signerFullname": "string",
  • "signatureType": "graphic",
  • "forcedSignaturePNGBase64": "JVBERi0xLjYNJeLjz9MNCjI0IDA",
  • "isForensic": true,
  • "ignoreDownloadAll": false,
  • "pades": false,
  • "locale": "it",
  • "documents": [
    ],
  • "otp": {
    },
  • "extraChecks": [
    ],
  • "archetypeId": 85,
  • "signatureCustomisations": {
    },
  • "immediatePDFViewMobile": true,
  • "rejectable": true,
  • "expirationPeriod": 86400,
  • "expiresAt": "2018-02-14T14:25:57.000Z",
  • "deletedAt": "2018-02-14T14:25:57.000Z",
  • "deletedEvidence": true,
  • "userLandedAt": "2018-02-14T14:25:57.000Z",
  • "userTookoffAt": "2019-02-14T14:25:57.000Z",
  • "downloadableUntil": "2020-02-14T14:25:57.000Z",
  • "currentStatus": "CONCLUDED",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "tags": {
    },
  • "fUrl": "https://api.webtrust.kopjra.com:443/v1/i/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpX2lkIjoxMTM2MSwiaXNzIjoiaHR0cHM6Ly9hcGkuZ2F0ZXdheS5rb3BqcmEuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZ2F0ZXdheS5rb3BqcmEuY29tIiwiaWF0IjoxNjk5NTM4NzQ2LCJleHAiOjE3MDIxMzA3NDZ9.8DACcqUGS1_yqs5a3QW6X6prKdo0K2irKSSyCCncpio"
}

Get all signatures

You can use this endpoint to get all of your Signatures. In the future, you will also be able to search among signatures using custom tags (still to be implemented).

This endpoint retrieves all of your signatures. Please note that the attached files are not shown here: they are shown on a single-signature basis.

Authorizations:
http_basic_schema
query Parameters
top
integer [ 1 .. 25 ]
Default: 5

The maximum number of object to be returned.

skip
integer >= 0
Default: 0

The number of results to be skipped starting from the first result. Used for pagination.

emptyScope
boolean
Default: false

If true the DB queries will be optimized, but some of the attributes may not be returned. It is advised to use the GET by ID endpoint to retrieve the full object.

sortBy
string
Example: sortBy=oMethod,-createdAt

A sorting criteria. It must be specified as comma separated list of terms, where each term can be: prop or +prop or -prop. The operator + or the absence of it indicates an ascending sorting direction, whereas the - operator indicates a descending sorting direction. prop can be one of the following:

  • id
  • currentStatus
  • expiresAt
  • userLandedAt
  • userTookoffAt
  • archetypeId
  • createdAt
  • updatedAt

For example a valid sorting criteria specification would be:

sortBy=currentStatus,-createdAt

With this criteria you will get a list of signatures sorted by currentStatus and for each equal currentStatus then it will be sorted by createdAt in descending order.

signerFullname
string

The full name of the signer.

currentStatus
string
Enum: "SUBSCRIBED" "POD_FAILED" "CONCLUDING" "CONCLUDED"

The current status of the signature.

createdAt
string
Example: createdAt=2018-02-01T12:34:23|2018-04-01T12:34:23

Range of timestamps with one of the following formats:

  • YYYY-MM-DDTHH:mm:ss|YYYY-MM-DDTHH:mm:ss = closed date range
  • |YYYY-MM-DDTHH:mm:ss = opened date range (no start date)
  • YYYY-MM-DDTHH:mm:ss = opened date range (no end date)
archetypeId
integer >= 1

Get the signatures corresponding to the specified archetype id.

tag:anyTagName
string
Example: tag:anyTagName=tagValue

You can filter your signatures by specifying a single tag:tagName=tagValue pair in the query. Notice the prefix tag: that needs to be prepended to the tag name that we want to use.

users
Array of strings
Example: users=externalUserId1,externalUserId2

Only if you are an admin, you can get all of the signatures belonging to your specified users

header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "https://api.webtrust.kopjra.com/v1/signatures"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

# TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
[
  • {
    }
]

Get a signature by Id

This endpoint retrieves a specific signature, including any tag and signed URLs that can be used to download any available attached file.

Authorizations:
http_basic_schema
path Parameters
signatureId
required
number
Example: 85
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "{SERVER}/signatures/85"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "id": 83,
  • "signerFullname": "string",
  • "signatureType": "graphic",
  • "forcedSignaturePNGBase64": "JVBERi0xLjYNJeLjz9MNCjI0IDA",
  • "isForensic": true,
  • "ignoreDownloadAll": false,
  • "pades": false,
  • "locale": "it",
  • "documents": [
    ],
  • "otp": {
    },
  • "extraChecks": [
    ],
  • "archetypeId": 85,
  • "signatureCustomisations": {
    },
  • "immediatePDFViewMobile": true,
  • "rejectable": true,
  • "expirationPeriod": 86400,
  • "expiresAt": "2018-02-14T14:25:57.000Z",
  • "deletedAt": "2018-02-14T14:25:57.000Z",
  • "deletedEvidence": true,
  • "userLandedAt": "2018-02-14T14:25:57.000Z",
  • "userTookoffAt": "2019-02-14T14:25:57.000Z",
  • "downloadableUntil": "2020-02-14T14:25:57.000Z",
  • "currentStatus": "CONCLUDED",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "tags": {
    },
  • "extradata": "Extra data",
  • "auditTrailXML": "<auditTrail>...</auditTrail>",
  • "auditTrail": {
    },
  • "attachedFiles": {}
}

Deletes a signature by Id

This endpoint marks a specific signature as deleted. It will delete all evidence if present and mark the signature as deleted (setting a date)

Authorizations:
http_basic_schema
path Parameters
signatureId
required
number
Example: 85
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl -XDELETE "{SERVER}/signatures/85"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "error": "Internal Server Error",
  • "message": "An internal server error occurred"
}

aesProviders

In order to create AES Signatures one must register AES providers. See our knowledge base for details regarding the API usage, examples and more.

Create an AES Provider

Create an AES Provider that could be then used to create and managed AES Signatures

Authorizations:
http_basic_schema
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"
Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
name
required
string <= 255 characters

The name of the AES provider

email
required
string <= 255 characters

The email of the AES provider

vatNumber
required
string(^IT[0-9]{11}$)

The VAT number of the AES provider, starting with the country code (at this moment only IT is supported).

Responses

Request samples

Content type
application/json
{
  • "name": "AES Provider",
  • "email": "aesprovider@email.com",
  • "vatNumber": "IT12345678901"
}

Response samples

Content type
application/json
{
  • "id": 123,
  • "name": "AES Provider",
  • "email": "aesprovider@email.com",
  • "vatNumber": "IT12345678901"
}

Get all AES Providers

You can use thus endpoint to get all of your registered AES Providers.

Authorizations:
http_basic_schema
query Parameters
top
integer [ 1 .. 25 ]
Default: 5

The maximum number of object to be returned.

skip
integer >= 0
Default: 0

The number of results to be skipped starting from the first result. Used for pagination.

sortBy
string
Example: sortBy=-name

A sorting criteria. It must be specified as comma separated list of terms, where each term can be: prop or +prop or -prop. The operator + or the absence of it indicates an ascending sorting direction, whereas the - operator indicates a descending sorting direction. prop can be one of the following:

  • id

  • name

  • email

  • vatNumber For example a valid sorting criteria specification would be:

    sortBy=-name

With this criteria you will get a list of signatures sorted by currentStatus and for each equal currentStatus then it will be sorted by createdAt in descending order.

name
string

The name of the AES Provider

email
string

The email of the AES Provider

vatNumber
string

The vatNumber of the AES Provider

header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "https://api.webtrust.kopjra.com/v1/aesProviders"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

# TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
[
  • {
    }
]

Get an AES Provider by Id

This endpoint retrieves a specific AES Provider.

Authorizations:
http_basic_schema
path Parameters
aesProviderId
required
number
Example: 2
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "{SERVER}/aesProvider/2"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "id": 123,
  • "name": "AES Provider",
  • "email": "aesprovider@email.com",
  • "vatNumber": "IT12345678901"
}

Deletes an AES Provider by Id

ONLY FOR ADMINISTRATORS' USE: Please contact support@kopjra.com if you want to delete an AES Provider.

This endpoint marks a specific AES Provider as deleted. It won't be considered anymore for the creation of new signatures.

Authorizations:
http_basic_schema
path Parameters
aesProviderId
required
number
Example: 2
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl -XDELETE "{SERVER}/aesProviders/2"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "error": "Internal Server Error",
  • "message": "An internal server error occurred"
}

aesSignatures

Document Advanced API

This solution allows us to create and manage Advanced Electronic Signatures (AES). The canonical use case for this solution is a company that wants contracts to be signed electronically and needs the signature to be AES (i.e. it needs recognition of the signer, PAdES signatures applied to the document and legally compliant archiving of the signed documents + the audit trail of the signature).

See our knowledge base for details regarding the API usage, examples and more.

Create an aesSignature

To be defined

Authorizations:
http_basic_schema
path Parameters
aesProviderId
required
number
Example: 2
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"
Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
required

Signature creation object

signerFullname
required
string

Full name of the signer

signatureType
required
string
Enum: "graphic" "fullname_date" "none"

Signature type can be a graphic stroke, an automatically generated text from the signer's fullname or nothing at all. This value defines what will be shown in the signature field inside the PDF.

forcedSignaturePNGBase64
string <byte>

PNG in base64 to be forced as signature when the signatureType is graphic. This PNG will be used instead of asking the signer for the graphic signature strokes. The PNG will be shown to the signer as a preview of the signature inside the signing environment.

ignoreDownloadAll
boolean
Default: false

This field makes sense when we are signing multiple documents. There is a functionality inside the signing environment that allows the signer to download all the documents at once. If this property is true the signer won't be able to download all the documents at once, but only one by one.

locale
string
Enum: "it" "en" "fr" "es" "de"

Language to be used in the texts provided automatically in the signing environment. WARN! It is a responsibility of the caller to translate accordingly all other custom texts, like extraChecks, smsCustomMessage and all customization to the pages.

extradata
string <= 262144 characters

It is a free text field that can be used to store any kind of information. This field won't transit to the signing environment. It is useful to store information that may be related to the signature process and isn't small.

required
Array of objects [ 1 .. 50 ] items

The documents to be signed.

object

The OTP sending method to be used for the signature. At least one of the two methods must be specified. When both are specified, SMS will be used as the primary method and email as the secondary one, in case the phone number validation fails, due to not supported country code.

Array of objects >= 0 items

Additional checkboxes to be added into the form of the signing page, external to the PDF document to be signed.

archetypeId
integer >= 1

If the signature has an archetype, this field represents the archetype's unique identifier.

object

The customisations you applied to a Signature resource. Every field is optional.

immediatePDFViewMobile
boolean
Default: false

If true immediately shows the PDF in the signing environment. This option can be true only when the amount of document is 1

rejectable
boolean
Default: false

If true the interaction can be refused in the signing environment via a Refuse button under the main call to action. If the interaction is refused, the its status will be REJECTED

object

An object representing the tags to be added to the Interaction. Note: tag names can only contain US-ASCII letters and/or numbers, whereas tag values can be any UTF-8 string. The key max length must be 100 and the value max length must be 255.

authProvider
string
Enum: "spid" "cie"

The authentication provider. When not specified, the signer will be prompted to choose one.

signerFiscalCode
required
string^TINIT-.*

The fiscal code of the signer

Responses

Request samples

Content type
application/json
{
  • "signerFullname": "string",
  • "signatureType": "graphic",
  • "forcedSignaturePNGBase64": "JVBERi0xLjYNJeLjz9MNCjI0IDA",
  • "isForensic": true,
  • "ignoreDownloadAll": false,
  • "pades": false,
  • "locale": "it",
  • "extradata": "Extra data",
  • "documents": [
    ],
  • "otp": {
    },
  • "extraChecks": [
    ],
  • "archetypeId": 85,
  • "signatureCustomisations": {
    },
  • "immediatePDFViewMobile": true,
  • "rejectable": true,
  • "tags": {
    },
  • "authProvider": "spid",
  • "signerFiscalCode": "TINIT-PRZLSU89R12A944G"
}

Response samples

Content type
application/json
{
  • "id": 83,
  • "signerFullname": "string",
  • "signatureType": "graphic",
  • "forcedSignaturePNGBase64": "JVBERi0xLjYNJeLjz9MNCjI0IDA",
  • "isForensic": null,
  • "ignoreDownloadAll": false,
  • "pades": null,
  • "locale": "it",
  • "documents": [
    ],
  • "otp": {
    },
  • "extraChecks": [
    ],
  • "archetypeId": 85,
  • "signatureCustomisations": {
    },
  • "immediatePDFViewMobile": true,
  • "rejectable": true,
  • "expirationPeriod": 86400,
  • "expiresAt": "2018-02-14T14:25:57.000Z",
  • "deletedAt": "2018-02-14T14:25:57.000Z",
  • "deletedEvidence": true,
  • "userLandedAt": "2018-02-14T14:25:57.000Z",
  • "userTookoffAt": "2019-02-14T14:25:57.000Z",
  • "downloadableUntil": "2020-02-14T14:25:57.000Z",
  • "currentStatus": "CONCLUDED",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "tags": {
    },
  • "aesProviderId": 123,
  • "authProvider": "spid",
  • "signerFiscalCode": "TINIT-PRZLSU89R12A944G",
  • "fUrl": "https://api.webtrust.kopjra.com:443/v1/i/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpX2lkIjoxMTM2MSwiaXNzIjoiaHR0cHM6Ly9hcGkuZ2F0ZXdheS5rb3BqcmEuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZ2F0ZXdheS5rb3BqcmEuY29tIiwiaWF0IjoxNjk5NTM4NzQ2LCJleHAiOjE3MDIxMzA3NDZ9.8DACcqUGS1_yqs5a3QW6X6prKdo0K2irKSSyCCncpio"
}

Get all AES signatures

You can use this endpoint to get all of your AES Signatures. In the future, you will also be able to search among signatures using custom tags (still to be implemented).

This endpoint retrieves all of your signatures. Please note that the attached files are not shown here: they are shown on a single-signature basis.

Authorizations:
http_basic_schema
path Parameters
aesProviderId
required
number
Example: 2
query Parameters
top
integer [ 1 .. 25 ]
Default: 5

The maximum number of object to be returned.

skip
integer >= 0
Default: 0

The number of results to be skipped starting from the first result. Used for pagination.

emptyScope
boolean
Default: false

If true the DB queries will be optimized, but some of the attributes may not be returned. It is advised to use the GET by ID endpoint to retrieve the full object.

sortBy
string
Example: sortBy=oMethod,-createdAt

A sorting criteria. It must be specified as comma separated list of terms, where each term can be: prop or +prop or -prop. The operator + or the absence of it indicates an ascending sorting direction, whereas the - operator indicates a descending sorting direction. prop can be one of the following:

  • id
  • currentStatus
  • expiresAt
  • userLandedAt
  • userTookoffAt
  • archetypeId
  • createdAt
  • updatedAt

For example a valid sorting criteria specification would be:

sortBy=currentStatus,-createdAt

With this criteria you will get a list of signatures sorted by currentStatus and for each equal currentStatus then it will be sorted by createdAt in descending order.

signerFullname
string

The full name of the signer.

currentStatus
string
Enum: "SUBSCRIBED" "POD_FAILED" "CONCLUDING" "CONCLUDED"

The current status of the signature.

createdAt
string
Example: createdAt=2018-02-01T12:34:23|2018-04-01T12:34:23

Range of timestamps with one of the following formats:

  • YYYY-MM-DDTHH:mm:ss|YYYY-MM-DDTHH:mm:ss = closed date range
  • |YYYY-MM-DDTHH:mm:ss = opened date range (no start date)
  • YYYY-MM-DDTHH:mm:ss = opened date range (no end date)
archetypeId
integer >= 1

Get the signatures corresponding to the specified archetype id.

tag:anyTagName
string
Example: tag:anyTagName=tagValue

You can filter your signatures by specifying a single tag:tagName=tagValue pair in the query. Notice the prefix tag: that needs to be prepended to the tag name that we want to use.

header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "https://api.webtrust.kopjra.com/v1/aesProviders/2/aesSignatures"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

# TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
[
  • {
    }
]

Get an AES signature by Id

This endpoint retrieves a specific AES signature, including any tag and signed URLs that can be used to download any available attached files.

Authorizations:
http_basic_schema
path Parameters
aesProviderId
required
number
Example: 2
aesSignatureId
required
number
Example: 85
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "{SERVER}/aesProviders/2/aesSignatures/85"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{}

Deletes an AES signature by Id

This endpoint marks a specific AES signature as deleted. It will delete all evidence if present and mark the signature as deleted (setting a date)

Authorizations:
http_basic_schema
path Parameters
aesProviderId
required
number
Example: 2
aesSignatureId
required
number
Example: 85
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl -XDELETE "{SERVER}/aesProviders/2/aesSignatures/85"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "error": "Internal Server Error",
  • "message": "An internal server error occurred"
}

timestamps

This API solution allows you to timestamp any data flow, like documents and log files. There are two types of timestamp that could be used:

  • Qualified:For this kind of timestamp a Trust Service Provider will be used to timestamp the data,
  • Trustless: In this case the timestamp will be done using the Bitcoin blockchain.

To create a timestamp we just need to make an API call to the endpoint createTimestamp passing a binary body containing the data to be timestamped. While creating the timestamp we can select what type to use by specifying the parameter trusted that can be true or false.

See our knowledge base for details regarding the API usage, examples and more.

Timestamp binary data

Calling this method one can timestamp a data flow by using a trusted timestamp (using a Trust Service Provider) or using an open-timestamp (based on Bitcoin)

Authorizations:
http_basic_schema
query Parameters
sync
boolean
Value: true
Example: sync=true

Indicates whether the stamp will be synchronous or asynchronous. Synchronous meaning the this call will end with a timestamped data flow as a response. For now, this parameter must always be true

trusted
boolean
Example: trusted=false

If true a Trust Service Provider will be used to timestamp the data, otherwise a Open-Timestamp (with Bitcoin) will be used.

fileName
string
Example: fileName=file.log

The name of the file to be timestamped.

header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/octet-stream"
Content-Type
required
string
Value: "application/octet-stream"
Request Body schema: application/octet-stream
string <binary>

Responses

Request samples 

curl "{SERVER}/timestamps?sync=true&trusted=false&fileName=file.log"
  -X POST
  --data-binary "@./file.log"
  -H "Accept: application/octet-stream"
  -H "Content-Type: application/octet-stream"
  -H "Authorization: Basic id:secret"

# TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "error": "Bad Request"
}

credentials

To make API calls to WT credentials are needed for the Authorization header. There are two ways of creating new credentials:

  1. Using the developer portal.
  2. Making this call by using other already created credentials.

    Note that the first time the developer portal must be used to create the credentials.

Creates new credentials

This API call will allow you to create new credentials. Credentials are not exclusive, they accumulate. A user can create a maximum of 2 credentials.

The secret will only be visible at the moment of the creation the credentials. So any further visualization of the credential won't contain the secret.

Authorizations:
http_basic_schema
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
X-Impersonate-User
string
Example: <externalUserId>
Request Body schema: application/json
required

empty object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "99a23d0349ad4c30e49dd08089507d4bb097e89ecb51d351158e30de0bdf321e94f848ce877336a5a7d0720a463b6ee8b80f1aa83581d42f7493d84bbc1b1dce",
  • "secret": "akfW02-fr2yQpt-XscaNpEosF0-99VoaK8Ox-lbeJR0xaD2cDOgNFxJ9i_4QRNjDhVvsevYy4qGoIG6r3w3yIUTNsS90niyLBnyF7jXIHTc1h7GBhRYMaAx8uTKhuy3QyLd2-xz4avjef0uPf_lhJF_3uvu0BZwb0RNQPWF_LKo"
}

Get credentials

This API call will allow you to retrieve all the credentials associated to the user (or the impersonated one).

Note that the secret is not visible anymore.

Authorizations:
http_basic_schema
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
X-Impersonate-User
string
Example: <externalUserId>

Responses

Request samples 

curl "{SERVER}/users/current/credentials"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
[
  • {
    }
]

Remove a credential

This endpoint allows you to delete a credential. From the moment this is done, the removed credential can not be used anymore in the Authorization header to authenticate an API call.

Authorizations:
http_basic_schema
path Parameters
credentialId
required
string
Example: 99a23d0349ad4c30e49dd08089507d4bb097e89ecb51d351158e30de0bdf321e94f848ce...
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
X-Impersonate-User
string
Example: <externalUserId>

Responses

Request samples 

curl "https://api.webtrust.kopjra.com/v1/users/current/credentials/99a23d0349ad4c30e49dd08089507d4bb097e89ecb51d351158e30de0bdf321e94f848ce877336a5a7d0720a463b6ee8b80f1aa83581d42f7493d84bbc1b1dce"
  -X DELETE
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
Example
{
  • "error": "Forbidden",
  • "message": "User cannot be impersonated"
}

callbacks

Callbacks are a way to notify the company's systems that a certain interaction/signature has changed status. The callback is sent to the company's system via a POST request to the URL specified in the callback's property endpoint.

See our knowledge base for details regarding the API usage, examples and more.

Create new callback

This API call will allow you to create new callback subscriptions. The designated endpoint will receive a callback when a relevant event happens.

Authorizations:
http_basic_schema
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
X-Impersonate-User
string
Example: <externalUserId>
Request Body schema: application/json
required

Interaction creation object

kind
string
Deprecated
Value: "simple-http"

The kind of callback (currently only 'simple-http'). Ignored and no longer used.

resourceType
required
string
Enum: "Interaction" "Signature"

The type of resource to receive the callback.

endpoint
required
string

The endpoint of the callback subscription

onlyFinalStatuses
boolean
Default: true

If true, the callback is called only when resources of the type defined get to a final status. Otherwise, the callback is called whenever resources change status.

events
Array of strings
Items Value: "USER_CONCLUDED"

If set (together with onlyFinalStatuses=false) it will call the callback for the specified events, besides the change of status. Note that specifying the parameter onlyFinalStatuses=true and events=[...], will produce a 400 error.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get callbacks

This API call will allow you to retrieve all the callbacks associated to the user (or the impersonated one).

Authorizations:
http_basic_schema
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
X-Impersonate-User
string
Example: <externalUserId>

Responses

Request samples 

curl "{SERVER}/users/current/callbacks"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
[]

Remove a callback

This endpoint allows you to delete a callback. From the moment this is done, the removed endpoint will no longer receive any callback notification.

Authorizations:
http_basic_schema
path Parameters
callbackId
required
string
Example: 123
header Parameters
Authorization
required
string
Example: Basic <base64-credential-string>
X-Impersonate-User
string
Example: <externalUserId>

Responses

Request samples 

curl "{SERVER}/users/current/credentials/123"
  -X DELETE
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
Example
{
  • "error": "Forbidden",
  • "message": "User cannot be impersonated"
}

archives

The acquisition package (outcome of an interaction), is downloadable for a certain amount of time, specified by the interaction's property downloadableUntil. To avoid that the company finds itself in a situation where it isn't able to download its acquisitions anymore, we devised an automatic Archiving mechanism.

This mechanism creates and indexed standalone package with all the interactions that took place within the a year (from January 1st to December 31st). This package is downloadable for a month from its creation, and afterwards it will be deleted from our systems.

Get archives

Retrieves all the corresponding archives to the authenticated user.

Authorizations:
http_basic_schema
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "{SERVER}/archives"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
[
  • {
    }
]

Get an archive by Id

Retrieves an specific archive.

Authorizations:
http_basic_schema
path Parameters
archiveId
required
number
Example: 123
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "{SERVER}/archives/1"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{
  • "id": 1,
  • "startsOn": "2019-01-01T00:00:00Z",
  • "endsOn": "2019-12-31T23:59:59Z",
  • "targetResources": [
    ],
  • "expiresOn": "2020-02-01T00:00:00Z",
  • "partMaxDimension": "DVD_SINGLE_SIDED_SINGLE_LAYER",
  • "format": "ZIP_EXPORT",
  • "sizeByte": 1343432145,
  • "status": "READY"
}

Get all parts of an archive

Retrieves all the parts associated to the specified archive.

Authorizations:
http_basic_schema
path Parameters
archiveId
required
number
Example: 123
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "{SERVER}/archives/1/parts"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
[]

Get a specific part of an archive

Retrieves a specific parts associated to the specified archive.

Authorizations:
http_basic_schema
path Parameters
archiveId
required
number
Example: 123
partId
required
number
Example: 456
header Parameters
Content-Type
required
string
Value: "application/json"
Authorization
required
string
Example: Basic <base64-credential-string>
Accept
required
string
Value: "application/json"

Responses

Request samples 

curl "{SERVER}/archives/1/parts"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

Content type
application/json
{}