signdoc/pades

The signdoc/pades API is used in the context of PAdES electronic signing. For a quick-start, please refer to our Get started with electronic signing guide for electronic signing.

Overview

URLhttps://<signdoc-baseurl>/signdoc/pades
AuthorizationAccess Token as Bearer Token in Authorization Header


Upload sign order to SignDoc resource server

POST [signdoc-baseurl]/signdoc/pades

Request

Headers

Key

Value

Authorization

Bearer access_token

Content-Type

application/json

Request body

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)

endUserOnlyboolean

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:

keytypedescription
xnumberHorizontal positioning of seal.
ynumberVertical positioning
of seal.
pageintegerPage 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)

pdfSpecstring

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...",
"pdfSpec:" "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 specifierdescription
padesSignedPdfResult contains the signed PDF as a base64 encoded string
documentHashResult contains the SHA256 hash over the unsigned and sign document hash
padesAppendixResult contains the appended signature data to the original PDF document as a base64 encoded string 

*Cannot be used when pdfSpec is set

["padesSignedPdf", "padesAppendix", "documentHash"]

Example request

POST [signdoc-baseurl]/signdoc/pades
Request body:
{
    "signProperties": {
"orderName": "My order name",
"documentDisplayMode": "interior",
"showConfirmation": true,
"showUnderstanding": true
},
"padesSignProperties": {
"addVisualSeals": true
},
"documents": [
{
"description": "Document to sign",
"pdf": "JVBER...",
"endUserOnly": false,
"merchantSealPos": {
"x": 20,
"y": 20,
"page": 1
},
"endUserSealPos": {
"x": 200,
"y": 20,
"page": 1
}
},
{
"description": "Another document to sign",
"pdf": "JVBER...",
"endUserOnly": true
}
],
"resultContent": [
"padesSignedPdf",
"padesAppendix",
"documentHash"
]
}

Response

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

GET [signdoc-baseurl]/signdoc/pades

Request

Headers

KeyValue
AuthorizationBearer access_token

Query parameters

ParameterTypeDescription
sign_idstringThe sign_id that was return when uploading the signing order.

Example request

GET [signdoc-baseurl]/signdoc/pades?sign_id=4120de56-4391-4e5a-adea-a28e62daac7e

Response

CodeDescriptionExample JSON response content
200 OK

Sign order was found. Returns the order state.

Possible values are:

  • ORDER_RECEIVED
  • GRABBED_BY_IDP
  • GENERATING_MERCHANT_SEALS
  • USER_SIGNING
  • ADD_DOCUMENT_SECURITY_STORE
  • FAILED
  • CANCELLED
  • SIGN_COMPLETED
{
"orderState": "ORDER_RECEIVED"
}
204 No Content

Sign order was not found.

This could be caused by timeout or an invalid sign_id.

(empty)

400 Bad RequestThe query parameter sign_id was not provided.
signId can not be empty - Please provide reference: AbcDEf if reporting the problem.
403 ForbiddenAccess token is invalid or missing.
AccessToken is invalid - Please provide reference: AbcDEf if reporting the problem.



Delete sign order and download signing results

DELETE [signdoc-baseurl]/signdoc/pades

The sign order will be deleted if this request is made, regardless of sign order state.

Request

Headers

KeyValue
AuthorizationBearer access_token

Query parameters

ParameterTypeDescription
sign_idstringThe sign_id that was return when uploading the signing order.

Example request

DELETE [signdoc-baseurl]/signdoc/pades?sign_id=4120de56-4391-4e5a-adea-a28e62daac7e

Response

CodeDescriptionExample JSON response content
200 OK

Sign order was found.

The claims returned in the signing results depends on the values pass to the resultContent array when creating the order:

set byclaimdescription

documentHash

unsignedDocumentSha256

Hash over the original document (base64 encoded)

documentHash

signedDocumentSha256

Hash over the signed document (base64 encoded)

padesSignedPdf

padesSignedPdf

The signed pdf as a base64 encoded text string

padesAppendix

padesAppendix

The signature data added to the original PDF represented as base64

description
Description of the document

signId
The sign_id reference

orderState
The current order state

orderName
Name of the order


If order is not completed, i.e. order state is not SIGN_COMPLETED, the signing results will be an empty array.

{
"signingResults": [
{
"signedDocumentSha256": "u0XXG...",
"padesSignedPdf": "JVBER..."
"padesAppendix": "DQoxMiAw..."
"description": "My order name - 1",
"unsignedDocumentSha256": "QJ2y8..."
}
],
"signId": "4120de56-4391-4e5a-adea-a28e62daac7e",
"orderName": "My order name",
"orderState": "SIGN_COMPLETED"
}
204 No Content

Sign order was not found.

This could be caused by timeout or an invalid sign_id.

(empty)

400 Bad RequestThe query parameter sign_id was not provided.
signId can not be empty - Please provide reference: AbcDEf if reporting the problem.
403 ForbiddenAccess token is invalid or missing.
AccessToken is invalid - Please provide reference: AbcDEf if reporting the problem.