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

URL	`https://<signdoc-baseurl>/signdoc/pades`
Authorization	Access 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)

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...",
    "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 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 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

Key	Value
Authorization	Bearer `access_token`

Query parameters

Parameter	Type	Description
`sign_id`	string	The `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

Code	Description	Example 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 Request`	The query parameter `sign_id` was not provided.	signId can not be empty - Please provide reference: AbcDEf if reporting the problem.
`403 Forbidden`	Access 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

Key	Value
Authorization	Bearer `access_token`

Query parameters

Parameter	Type	Description
`sign_id`	string	The `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

Code Description Example 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 by	claim	description
`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 Request

The query parameter sign_id was not provided.

signId can not be empty - Please provide reference: AbcDEf if reporting the problem.

403 Forbidden

Access token is invalid or missing.

AccessToken is invalid - Please provide reference: AbcDEf if reporting the problem.

LATEST PROD (OIDC)

signdocpades

Overview

Upload sign order to SignDoc resource server

Request

Headers

Request body

Example request

Response

Response if `pdfSpec` is used

Check status of sign order

Request

Headers

Query parameters

Example request

Response

Delete sign order and download signing results

Request

Headers

Query parameters

Example request

Response

signdocpades

Overview

Upload sign order to SignDoc resource server

Request

Headers

Request body

Example request

Response

Response if pdfSpec is used

Check status of sign order

Request

Headers

Query parameters

Example request

Response

Delete sign order and download signing results

Request

Headers

Query parameters

Example request

Response

Response if `pdfSpec` is used