...
Key | Type / Description | Example JSON |
|---|
signProperties (required)
| JSON object: key | type | description | default value |
|---|
orderName
| string | Order name. | (required) | documentDisplayMode
| string | Must be "interior", "window" or "overlay". | "interior" | showConfirmation
| boolean | Show "Signing completed" in client after signing. | true | showUnderstanding
| boolean | Show box for "Content is understood" in client. | true | timeoutSeconds
| integer | Timeout in seconds for end user signing. | 1800 |
| "signProperties": {
"orderName": "My order name",
"documentDisplayMode": "interior",
"showConfirmation": true,
"showUnderstanding": true,
"timeoutSeconds": 1800
} |
padesSignProperties
(required)
| JSON object: key | type | description | default value |
|---|
addVisualSeals
| boolean | If true, add visual signature seals to PDF. | (required) |
| "padesSignProperties": {
"addVisualSeals": true
} |
documents
| JSON array of documents to be signed (minimum one). The document to be signed is represented as a JSON object: key | type | description | default value |
|---|
description
| string | Description of document. Displayed to end user in client. If not specified, orderName from signProperties will be used combined with a number, i.e. "My order name - 1" for the first document. | (optional) | pdf
| string | Base64 encoded PDF | (required) | endUserOnly | boolean | Set to true if only the end user signature is desired.
| false | merchantSealPos
| JSON object: key | type | description |
|---|
x
| number | Horizontal positioning of seal. | y
| number | Vertical positioning of seal. | page
| integer | Page number to place seal. |
| Specifies the position of merchant signature seal in PDF. The seal will be positioned according to the x and y coordinates (in points) with origin in the upper left corner. The visual seal size is adjusted according to the DPI of the document. If the page number is out of range it will be the seal will be placed on the first page. If the coordinates are out of bounds the seal will be placed below and left of existing seals or in the upper left corner if no other seals exist. See COI documentation for further details. | (optional) | endUserSealPos
| JSON object: | key | type | description |
|---|
x | number | Horizontal positioning of seal. | y | number | Vertical positioning
of seal. | page | integer | Page number to place seal. |
| Specifies the position of merchant signature seal in PDF. The seal will be positioned according to the x and y coordinates (in points) with origin in the upper left corner. The visual seal size is adjusted according to the DPI of the document. If the page number is out of range it will be the seal will be placed on the first page. If the coordinates are out of bounds the seal will be placed below and left of existing seals or in the upper left corner if no other seals exist. See COI documentation for further details. | (optional) | pdfSpec | string | Validates and if necessary converts the document (pdf) to specified PDF/A version and conformance level. Currently only PDFA_2B is currently supported and conversion is only active in production.
| (optional) |
Be aware that very large PDF files, typically files with a large number of images, might give a less than optimal user experience due to the document processing time. The total package size has no upper limit,but we recommend to keep the total size below 35MB.
| "documents": [
{ "description": "My document",
"pdf": "JVBER...",
"merchantSealPospdfSpec:": { "PDFA_2B",
"merchantSealPos": {
"x": 100,
"y": 80,
"page": 1
},
"endUserSealPos": {
"x": 200,
"y": 80,
"page": 1
}
}
] |
resultContent
(required) | JSON array of string. Must contain at either padesSignedPdf, or padesAppendix, or both. The string values will determine the content result when retrieving a completed sign order later: | result specifier | description |
|---|
padesSignedPdf | Result contains the signed PDF as a base64 encoded string | documentHash | Result contains the SHA256 hash over the unsigned and sign document hash | padesAppendix | Result contains the appended signature data to the original PDF document as a base64 encoded stringstring
*Cannot be used when pdfSpec is set |
| ["padesSignedPdf", "padesAppendix", "documentHash"] |
...
Content-Type: application/json
Code | Description | Example JSON response content |
|---|
201 Created | Successfully uploaded PAdES sign order | {
"sign_id": "4120de56-4391-4e5a-adea-a28e62daac7e"
} |
400 Bad request | Could not create order due to error in request. See the "errors"-array in the response for details. | {
"errors": [
"Missing field: 'orderName'",
"Missing field: 'padesSignProperties'",
"'resultContent' must contain at least one of 'padesSignedPdf' or 'padesAppendix' for PAdES orders"
]
} |
403 Forbidden | Access token is invalid. | AccessToken is invalid - Please provide reference: AbcDEf if reporting the problem. |
Response if pdfSpec is used
Content-Type: application/json
Code | Description | Example JSON response content |
|---|
201 Created | Successfully uploaded and converted PAdES sign order conversionWarnings contains an array of warnings that occurred during the conversion. Possible values are: - VISUAL_DIFF("Visual differences in output PDF")
- COLORANTS("Resolve name collisions of colorants")
- OCG_REMOVED("Removed optional content groups (layers)")
- TRANSP_REMOVED("Transparency removed")
- XMP_REMOVED("Removed non convertible XMP metadata")
- FONT_SUBST("Font substituted")
- ACTION_REMOVED( "Removed interactive elements such as actions or annotations")
- STRUCTURE_REMOVED("Structure removed")
In CURRENT the response will always be DISABLED("PDF conversion is disabled") and "converted" = false | {
"sign_id": "6adc9075-5a02-4152-ae26-7cc75da469eb",
"conversionResults": [
{
"conversionId": "d886b218-af9f-4765-a9e1-d819fec6abbe",
"description": "My order name - 1",
"converted": true,
"conversionErrors": [],
"conversionWarnings": [
"Visual differences in output PDF",
"Removed interactive elements such as actions or annotations"
]
},
{
"conversionId": "1b4c673a-9d9e-4680-8aa2-810a31d50d8c",
"description": "My order name - 2",
"converted": true,
"conversionErrors": [],
"conversionWarnings": [
"Visual differences in output PDF",
"Removed interactive elements such as actions or annotations"
]
}
]
} |
400 Bad request | Could not convert order due to error in request. Documents that could not be converted will have a list of errors in conversionErrors. Possible conversionErrors are: - CORRUPT("Document is corrupt")
- DOC_SIGNED("Document contains signatures")
- EF_REMOVED("Embedded files removed")
- GENERIC_ERROR("Unknown error")
- DISABLED("PDF conversion is disabled")
| {
"conversionResults": [
{
"conversionId": "90c3803b-5e90-400c-b945-02ce223d65be",
"description": null,
"converted": true,
"conversionErrors": [],
"conversionWarnings": [
"Visual differences in output PDF",
"Removed interactive elements such as actions or annotations"
]
},
{
"conversionId": "fe7c3db8-e586-4253-960b-771ba6d170a1",
"description": null,
"converted": true,
"conversionErrors": [],
"conversionWarnings": [
"Visual differences in output PDF",
"Removed interactive elements such as actions or annotations"
]
},
{
"conversionId": "d796513c-ae65-4a9b-a3ae-f6652d4f7a2b",
"description": null,
"converted": false,
"conversionErrors": [
"Document contains signatures"
],
"conversionWarnings": []
}
]
} |
403 Forbidden | Access token is invalid. | AccessToken is invalid - Please provide reference: AbcDEf if reporting the problem. |
...
Check status of sign order
...
