signdoc

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

Overview

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


Upload sign order to SignDoc resource server

POST [signdoc-baseurl]/signdoc

Request

Headers

KeyValue
AuthorizationBearer access_token
Content-Typeapplication/json

Request body

KeyType / DescriptionExample JSON
signProperties

JSON object:

keytypedescriptiondefault value
orderNamestringOrder name(required)
documentDisplayModestringMust be "interior", "window" or "overlay"."interior"
showConfirmationbooleanShow "Signing completed" in client after signing.true
showUnderstandingbooleanShow box for "Content is understood" in client.true
timeoutSecondsintegerTimeout in seconds for end user signing.1800
"signProperties": {
"orderName": "My order name",
"documentDisplayMode": "interior",
"showConfirmation": true,
"showUnderstanding": true,
"timeoutSeconds": 1800
}

documents

JSON array of documents to be signed (minimum one).

The document to be signed is represented as a JSON object:

keytypedescriptiondefault value
descriptionstring

Description of document. Displayed to end user in client.

If not specified, orderName from signProperties will be used combined with a number,
e.g. "My order name - 1" for the first document.

(optional)
textstringText to sign.(optional)*
pdfstringBase64 encoded PDF.(optional)*
xmlstringXML. Must be used together with "xsl".(optional)*
xslstringXML Stylesheet. Must be used together with "xml".(optional)*

*Each document must provide a value for either "text", "pdf" or the pair "xml" and "xsl".

"documents": [
{
"description": "My PDF document",
"pdf": "JVBER..."
},
{
"description": "My text",
"text": "My text to sign...",
},
{
"xml": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?> ...",
"xls": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?><xsl:stylesheet ..."
}
]
resultContent

JSON array of string.

The string values will determine the content result when retrieving a completed sign order:

result specifierdescription
basicSignatureResult contains the end user and merchant signatures (in ISO-8859 text format)
documentHashResult contains the SHA256 hash over the documents to be signed (in UTF-8 text format).
sdo

Result contains the documents and signature data in the SEID-SDO format.

["basicSignature", "documentHash", "sdo"]

Example request

POST [signdoc-base-url]/signdoc
Request body:
{
"signProperties": {
"orderName": "My order name",
"documentDisplayMode": "interior",
"showConfirmation": true,
"showUnderstanding": true
},
"documents": [
{
"text": "My text to sign"
},
{
"description": "My PDF order",
"pdf": "JVBER..."
}
],
"resultContent": [
"sdo",
"basicSignature",
"documentHash"
]
}

Response

Content-Type: application/json

CodeDescriptionExample JSON response content
201 CreatedSuccessfully created sign order.
{
"sign_id": "2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf",
}
400 Bad requestCould not create order due to error in request.
An order must have a name - Please provide reference: GHIjKl if reporting the problem.

403 Forbidden

Access token is invalid or missing.
AccessToken is invalid - Please provide reference: GHIjKl if reporting the problem.




Check status of sign order

GET [signdoc-baseurl]/signdoc

Request

Headers

KeyValue
AuthorizationBearer access_token

Query parameters

ParameterTypeDescription
sign_idstringThe sign_id that was returned when creating the sign order.

Example request

GET [signdoc_baseurl]/signdoc/pades?sign_id=2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf

Response

CodeDescriptionExample JSON response content
200 OK

Sign order was found. Returns the order state.

Possible values are:

  • ORDER_RECEIVED
  • GRABBED_BY_IDP
  • USER_SIGNING
  • FAILED
  • CANCELLED
  • SIGN_COMPLETED

204 No ContentSign order was not found
400 Bad RequestThe query parameter sign_id was not provided.
403 ForbiddenAccess token is invalid or missing.




Delete sign order and download signing results

DELETE [signdoc-baseurl]/signdoc

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 returned when creating the sign order.

Example request

DELETE [signdoc-baseurl]/signdoc?sign_id=2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf

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

basicSignature

merchantSignatures

Array of merchant signatures in ISO-8859 text format for each document in the same order they were provided when creating the sign order.

basicSignature

endUserSignatures

Array of end user signatures in ISO-8859 text format for each document in the same order they were provided when creating the sign order.

documentHash

documentHashes

Array of hashes over the documents to be signed in the same order as the documents in the signing order

sdo

sdos

The SEID-SDO represented as base64 (unpack to UTF-8), one for each document


signId

The sign_id used

clientId

The OIDC client used

orderState

Current order state

orderName

Name of order

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

{
"documentHashes": [
"5OKv0...",
"l5hoT...",
"PyLlx..."
],
"merchantSignatures": [
"MIAGC...",
"MIAGC...",
"MIAGC..."
],
"sdos": [
"PD94b...",
"PD94b...",
"PD94b...",
],
"endUserSignatures": [
"MIAGC...",
"MIAGC...",
"MIAGC..."
],
"clientId": "my-oidc-client-id",
"signId": "2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf",
"orderState": "SIGN_COMPLETED",
"orderName": "My order name"
}
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 should not be empty - Please provide reference: GHIjKl if reporting the problem.

403 Forbidden

Access token is invalid or missing.
Could not find accessToken - Please provide reference: GHIjKl if reporting the problem.



Additional examples of sign order upload requests to SignDoc resource server

Simplified sign flow expressed like a full flow

The signing order below behaves identically to the simplified flow given by sign_txt=VGhlIHNpbmdfdHh0IGdpdmVuIGlzIHBsYWNlZCBoZXJl

{
"signProperties": {
"orderName":"bankID",
        "showUnderstanding":"true",
        "showConfirmation":"false",
        "documentDisplayMode": "interior",
        "timeoutSeconds":600
    },
    "documents": [
        {
"text":"The sign_txt given is placed here"
}
    ],
    "resultContent": [
"basicSignature",
"documentHash"
]
}

SEID-SDO: Two texts and one XML

{
"signProperties": {
"orderName": "test order",
"showUnderstanding": "true",
"showConfirmation": "false",
"documentDisplayMode": "overlay"
},
"resultContent": [
"sdo"
],
"documents": [
{
"description": "my first document to sign",
"text": "Testing å and ø...."
},
{
"text": "Short version of a document having two linefeeds\n\ndescription when listet in BankID WebClient should be 'test order - 2"
},
{
"description": "An xslt transformation",
"xml": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?><Persons><Person><Name>Ola Normann</Name><Street>Olaveien 99</Street><Zip>0014</Zip><City>Oslo</City></Person><Person><Name>Kalle</Name><Street>Ibsens veg 30</Street><Zip>9876</Zip><City>Stockholm</City></Person><Person><Name>Kari IngridsDottir</Name><Street>Nedre Sofustrøa 2</Street><Zip>7070</Zip><City>Bosberg</City></Person><Person><Name>Olava Olsen</Name><Street>Øvre Strete 12</Street><Zip>2211</Zip><City>Sørpå</City></Person></Persons>",
"xsl": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?><xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\"> xsl:output method=\"html\" encoding=\"ISO-8859-1\" doctype-system=\"http://www.w3.org/TR/html4/loose.dtd\" doctype-public=\"-//W3C//DTD HTML 4.01 Transitional//EN\" indent=\"yes\" /><xsl:template match=\"/\"><HTML><BODY><h2>Eksempel på XML/XSL.</h2><p>Under er en liste personer tatt fra XML-en</p><ul><xsl:for-each select=\"Persons/Person\"><xsl:if test=\"0 = position() mod 2\"><li style='color:red'><xsl:value-of select=\"Name\"/>,<xsl:value-of select=\"Street\"/>,<xsl:value-of select=\"Zip\"/>,<xsl:value-of select=\"City\"/></li></xsl:if><xsl:if test=\"1 = position() mod 2\"><li style='color:green'><xsl:value-of select=\"Name\"/>,<xsl:value-of select=\"Street\"/>,<xsl:value-of select=\"Zip\"/>,<xsl:value-of select=\"City\"/></li></xsl:if></xsl:for-each></ul></BODY></HTML></xsl:template></xsl:stylesheet>"
}
]
}