Get sign order info

Different information can be gathered from a customer's sign order. This can be information about a sign order status, the sign process, the sign order or a set of sign orders, the document to be signed, the signatures on a document and a log of all notifications.

The set of "Get" messages available:

GetSigningProcesses

The GetSigningProcesses message is used to fetch all sign processes for a given sign order and given signer based on the sign process status if stated. The sign URL (if not signed), the sign process status and the sign time (if signed) is returned. This message is the most commonly used message to retrieve a signer's sign URL. Other ways to retrieve the sign URL is to use either e-mail notification sent directly to the signer or XML notification sent to the customer's application so the application can make it available for the signer. Read more about XML notification call back.

This message is also used to check the status of a sign process. The status of a sign process is set to complete immediately after the signing has been performed. As a comparison, the status of a sign order is set to complete after all signatures has been set to complete and all post-processing of the sign order has been done. Post-processing includes creating and sealing the SDO, send notifications and archival.

Note: It is highly recommended to implement this message to retrieve the sign URL.

GetSigningProcesses.PNG 

​Name​Description​Constraints
​OrderID

​​​The OrderID sent by the customer.

​​​​

​MinLength = 1

MaxLength = 80

​LocalSignerReferenceA reference to a specific signer as defined when inserting the sign order. The sign processes for this signer will be shown as the result.
​​​​

​MinLength=1

MaxLength=100

​SigningProcessStatusFilter​The sign process status to filter by. If missing, all statuses will be shown.​[Active | Pending | Complete |  CancelledByMerchant | Expired | RejectedBySigner]

Back to top

GetSigningProcesses response

​Name​Description​Constraints
​OrderID

​​​The OrderID sent by the customer.


​​​​​​​

​MinLength = 1

MaxLength = 80

​TransRef​String uniquely identifying the transaction in E-Signing.​NA
​OrderDescriptionThe sign order description as it was defined by the customer when inserting the sign order.​Only present if provided when the order was inserted.
​OrderStatus​The status of the sign order. Read more about the different statuses. [Active | CancelledByMerchant | Expired | RejectedBySigner | Complete | ExpiredByProxy | Failed | Deleted]​
​SearchHits​The number if hits/ sign processes that match the filtering critereas. This value may be 0. If the value is 0 then the SigningProcessResults element is not present.​nonNegative Integer
​SigningProcessResults See table below.

NA

 

SigningProcessResults

​Name​Description​Constraints
​SigningProcessId​The sign process's internal id. ​​NA
​Status​The sign process status. ​​[Active | Complete | Pending | Expired | RejectedBySigner | CancelledByMerchant]
​LocalWebContextRefA reference to a specific webcontext defined when inserting the sign order. ​

​MinLength = 1

MaxLength = 100

​LocalSignerReference​A reference to a specific signer as defined when inserting the sign order. ​NA
​DocumentDetails / DocumentStatusThe status of the document. Read more about how it is derived. ​​[Active | Complete | Pending | Expired | RejectedBySigner | CancelledByMerchant | Deleted]
​DocumentDetails / LocalDocumentReferenceA reference to a specific document as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​DocumentDetails / Presentation / Title​The title of the document as defined when inserting the sign order.

​MinLength = 4

MaxLength = 60

​DocumentDetails / Presentation / Description​The description of the document as defined when inserting the sign order.

​MinLength = 4

MaxLength = 240

​DocumentDetails / DocType​The document format.​​[PDF | TEXT | XML]
​Attachments / AttachmentDetails / LocalAttachmentReference​A reference to a specific attachment as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​Attachments / AttachmentDetails / Presentation / Title​The title of the attachment as defined when inserting the sign order.

MinLength = 4

MaxLength = 60

​SignURL​​A HTTP address with the sign URL.The sign URL is the link to a specific sign process.  ​Only present if the sign process status is Active.
​SigningTime​​The signing time.​​Only present if the sign process status is Complete.

Back to top

GetOrderStatus

The GetOrderStatus message is a message used to request the complete status of a sign order. The message returns the status of the sign order, the documents, the signers, the steps and the sign processes.

Read more about all statuses in the service.

GetOrderStatus.PNG 

​Name​Description​Constraints
​OrderID

​​​The OrderID sent by the customer.


​​​​​

​MinLength = 1

MaxLength = 80

GetOrderStatus response

​Name​Description​Constraints
​OrderID

​​​The OrderID sent by the customer.

​​​

​MinLength = 1

MaxLength = 80

​TransRef​String uniquely identifying the transaction in E-Signing.​NA
​OrderDescriptionThe sign order description as it was defined by the customer when inserting the sign order.Only present if provided when the order was inserted.
​OrderStatus​The status of the sign order.​[Active | CancelledByMerchant | Expired | RejectedBySigner | Complete | ExpiredByProxy | Failed | Deleted]​
​StatusNote​A text note that explains the status of archival, signature and procuration checks, business certificate download and sealing of the order.

​Possible status notes:
[ArchivalStatus = Pending | Ready | InProgress | Complete | Failed]

[SignAndProcuraVerificationStatus = Pending | Ready | InProgress | Complete | Failed]

[BusinessCertificateStatus = Pending | Ready | InProgress | Complete | Failed]

[SealStatus = Pending | Ready | InProgress | Complete | Failed]

​DocumentStatuses / DocumentStatus / LocalDocumentReference​A reference to a specific document as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​DocumentStatuses / DocumentStatus / ​Status​The status of the document. ​[Active | Pending | CancelledByMerchant | Expired | RejectedBySigner | Complete | Deleted]
​SignerStatuses / SignerStatus / LocalSignerReferenceA reference to a specific signer as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​SignerStatuses / SignerStatus /  Status​The status of the signer. ​[Active | Pending | CancelledByMerchant | Expired | RejectedBySigner | Complete ]

​ExecutionDetailsStatus

See table below.​NA


 ExecutionDetails

​Name​Description​Constraints
​StepStatuses / StepStatus / StepNumber​​The step number as defined when inserting the sign order.​NA
​StepStatuses / StepStatus / Status​The status of the step. ​​[Active | Pending | CancelledByMerchant | Expired | RejectedBySigner | Complete]
​StepStatuses / StepStatus / SignProcessStatus / LocalDocumentReference​A reference to a specific document as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​StepStatuses / StepStatus / SignProcessStatus / LocalSignerReference​​​A reference to a specific signer as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​StepStatuses / StepStatus / SignProcessStatus / LocalAttachmentReferences / LocalAttachmentReference​A reference to a specific attachment as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​StepStatuses / StepStatus / SignProcessStatus / Status​​The status of the sign process.​​[Active | Pending | CancelledByMerchant | Expired | RejectedBySigner | Complete]
​StepStatuses / StepStatus / SignProcessStatus / RejectText​A text the signer can enter if he/she rejects to sign the document.​​Only present if the sign process status is RejectedBySigner and the signer provided this text.
​StepStatuses / StepStatus / SignProcessStatus /  Timestamp​The meaning of the time stamp depends on the sign process status. Time stamp is the sign time if status is Complete, and it is the rejection time if status is RejectedBySigner. ​​Only present if the sign process status is Complete or RejectedBySigner.
StepStatuses / StepStatus / SignProcessStatus / SigningPKI​This field tells which eID the signer used to sign the document in this sign process. ​       

Only present if status is Complete. Possible values:

[BankID | BankIDNOMobile | NemID | BankIDSE | NemID-OpenSign | PKI-OTP | Tupas ]

Back to top

GetOrderDetails

The GetOrderDetails message is used to retrive sign order details. It returns a subset of the sign order as it was inserted. The response to this message is not as comprehensive as the GetOrder message, but it gives an overview of the sign order and the current statuses.

GetOrderDetails.PNG 

​Name​Description​Constraints
​OrderID

​​​The OrderID sent by the customer.


​​​​

​MinLength = 1

MaxLength = 80

GetOrderDetails response

​Name​Description​Constraints
​OrderID

​​​The OrderID sent by the customer.

​​​

​MinLength = 1

MaxLength = 80

​TransRef​String uniquely identifying the transaction in E-Signing.​NA
​OrderDescription​The sign order description as it was defined by the customer when inserting the sign order.​Only present if provided when the order was inserted.
CreationTime​The time the sign order was inserted to E-Signing.​NA
​OrderStatus​​The status of the sign order.​​[Active | CancelledByMerchant | Expired | RejectedBySigner | Complete | ExpiredByProxy | Failed | Deleted]​
​StatusNote​​A text note that explains the status of archival, signature and procuration checks, business certificate download and sealing of the order.

​Possible status notes:

[ArchivalStatus = Pending | Ready | InProgress | Complete | Failed]

[SignAndProcuraVerificationStatus = Pending | Ready | InProgress | Complete | Failed]

[BusinessCertificateStatus = Pending | Ready | InProgress | Complete | Failed]

[SealStatus = Pending | Ready | InProgress | Complete | Failed]

Documents /​LocalDocumentReference​​A reference to a specific document as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

Documents / Presentation / Title​​The title of the document as defined when inserting the sign order.

​MinLength = 4

MaxLength = 60

​Documents / Presentation / Description​​The description of the document as defined when inserting the sign order.

​MinLength = 4

MaxLength = 240

Attachments / AttachmentDetails / LocalAttachmentReference​A reference to a specific attachment as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​Attachments / AttachmentDetails / Presentation / Title​The title of the attachment as defined when inserting the sign order.

MinLength = 4

MaxLength = 60

​ExecutionDetails​See the table below.​NA

ExecutionDetails

​Name​Description​Constraints
​OrderDeadline​The deadline of the sign order as defined when inserting the sign order. ​NA
​Steps / StepDetails / StepNumber​​​The step number as defined when inserting the sign order.​NA
​Steps / StepDetails / StepDeadline​The deadline of the step as defined when inserting the sign order. This value is the same as the sign order deadline if it was absent when inserting the sign order. ​NA
​Steps / StepDetails / Status ​The status of the step. ​​​[Active | Pending | CancelledByMerchant | Expired | RejectedBySigner | Complete]
​Steps / StepDetails / SignProcessDetailsSee the table below.​​NA

SigningProcessDetails

​Name​Description​Constraints
LocalDocumentReference​​​​A reference to a specific document as defined when inserting the sign order.

MinLength = 1

MaxLength = 100​

​LocalSignerReference​​​​A reference to a specific signer as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​LocalOrganizationRef​A reference to a specific organisation as defined when inserting the sign order.
​​​​​

​MinLength = 1

MaxLength=20

​SigningProcessDeadline​The deadline of the sign procsess as defined when inserting the sign order. This value is the same as the step deadline if it was absent when inserting the sign order. ​NA
​ReminderSettings / StartTime​The StartTime as defined by the customer when inserting the sign order.​NA
​ReminderSettings / IntervalT​he Interval in hours as defined by the customer when inserting the sign order. ​NA
​TerminateOnSignerRejection​The value as defined by the customer when inserting the sign order.​[true | false]
​Status​The status of the sign process.​[Active | CancelledByMerchant | Expired | RejectedBySigner | Complete]
​Timestamp​​The meaning of the time stamp depends on the sign process status. Time stamp is the sign time if status is Complete, and it is the rejection time if status is RejectedBySigner. ​Only present if the sign process status is Complete or RejectedBySigner.
​RejectText​A text the signer can enter if he/she rejects to sign the document.​Only present if the sign process status is RejectedBySigner and the signer provided this text.
​SigningPKI​This field tells which eID the signer used to sign the document in this sign process.

Only present if status is Complete. Possible values:

[BankID | BankIDNOMobile | NemID | BankIDSE | NemID-OpenSign | PKI-OTP | Tupas ]

Back to top

GetOrder

The GetOrder message returns the entire sign order as it was when the customer inserted it. The only difference may be that the values for deadlines for steps and sign processes has the same values as the deadline of the sign order. This is the case if the step and sign process deadlines was not defined when inserting the sign order.

GetOrder.PNG
 

​Name ​Description​Constraints
​OrderID​The OrderID sent by the customer.
​​​​

​MinLength = 1

MaxLength = 80

GetOrder response

The information returned in the GetOrderResponse is the same as the values used when inserting the sign order. See the InsertOrder message for information about the different elements.

 

Back to top

 

 

GetOrders

The GetOrders message is a search message that can filter on sign order status, signers, meta data and/or time. Note: Using the different filtering options may be time consuming and the response time may be significant higher than other E-Signing messages.

GetOrders.PNG 

​Name​Description​Constraints
​OrderStatusFilterA filter to search for all sign orders with a certain status. ​All sign orders with this status will be returned if this is the only filtering parameter.​[Active | CancelledByMerchant | Expired | RejectedBySigner | Complete | ExpiredByProxy | Failed | Deleted]
​SignerFilter / LocalSignerReferenceA filter to search for a particular signer using the LocalSignerReference defined when inserting the sign orders. All sign orders with this LocalSignerReference will be returned if this is the only filtering parameter.​NA
SignerFilter / ​SignerStatusA filter to search for a particular signer status. ​All sign orders with this signer status for the particular signer defined above is returned if this is the only filtering parameter. ​[Active | CancelledByMerchant | Expired | RejectedBySigner | Complete | Pending]
​MetaDataFilter / NameValuePair / NameA filter to search for a particular meta data name/value pair. ​The meta data name must match the name in a sign order. All sign orders with these name/value pairs will be returned if this is the only filtering parameter. ​NA
​MetaDataFilter / NameValuePair / Value

A filter to search for a particular meta data name/value pair. ​The meta data value must match the value in a sign order. All sign orders with these name/value pairs will be returned if this is the only filtering parameter.

​NA
​TimeFilter / StartTimeA filter to limit the ​search's time period. The start time defines the start of the time period and only sign orders created at and after this time will be a part of the search.  ​NA
​TimeFilter / EndTimeA filter to limit the ​search's time period. The end time defines the end of the time period and only sign orders created before this time will be a part of the search.  ​NA

Back to top

GetOrders response

The first part of the response returns the filtering criterias set in the GetOrders message and they are described there. The table below describes the result.

​Name​Description ​Constraints
​SearchHits​The number if hits that matches the filtering critereas. This value may be 0. If the value is 0 then the OrderResults element is not present.​​NA
​OrderResults​The result of the search. Will contain an OrderResult element for each search hit.  ​Only present if SearchHits are one or higher.
​OrderResults / OrderResult​For each sign order that matches that search filter, an OrderResult element is return. See table below for more information.​NA

 

OrderResult

 

​Name​Description​Constraints
​ResultOrderID​The OrderID of the a sign order matching the filters.
​​​​

​MinLength = 1

MaxLength = 80

​OrderDescription​The sign order description as it was defined by the customer when inserting the sign order.​Only present if provided when the order was inserted.
​OrderDeadline​The deadline of the sign order as defined when inserting the sign order. ​NA
​OrderStatus​The status of the sign order.​​​[Active | CancelledByMerchant | Expired | RejectedBySigner | Complete | ExpiredByProxy | Failed | Deleted]​
​StatusNote​​​A text note that explains the status of archival, signature and procuration checks, business certificate download and sealing of the order.

​Possible status notes:

[ArchivalStatus = Pending | Ready | InProgress | Complete | Failed]

[SignAndProcuraVerificationStatus = Pending | Ready | InProgress | Complete | Failed]

[BusinessCertificateStatus = Pending | Ready | InProgress | Complete | Failed]

[SealStatus = Pending | Ready | InProgress | Complete | Failed]

​SignerStatus​The status of the signer.​​[Active | Pending | CancelledByMerchant | Expired | RejectedBySigner | Complete ]
​MetaData / NameValuePair / Name​The meta data names that are a part of this sign order.

​Only present if MetaDataFilter was present in the request.

MinLength = 1

MaxLength=50

​MetaData / NameValuePair / Value​The meta data values that are a part of this sign order.

​Only present if MetaDataFilter was present in the request.

MinLength = 1

MaxLength=50

 

 

Back to top

GetDocuments

The GetDocuments message will return either a single or all documents in a specified sign order and/or the SDO's or partial SDO's. A partial SDO is a SDO including only one document and all signers that have have signed the document at the requested time. A partial SDO is generated after each completed sign process.  If all signers have signed a given document then the SDO (which is generated per document) is sealed. The document status is then set to Complete.

GetDocuments.PNG 

​Name​Description​Constraints
OrderID​​The OrderID sent by the customer.
​​​

​MinLength = 1

MaxLength = 80

​LocalDocumentReference​​A reference to a specific document as defined when inserting the sign order. If this value is present, only this document will be returned.

MinLength = 1

MaxLength = 100​

​ReturnDocumentSetting this to true will return either the specified document or all documents in the specified sign order. ​[true | false]
​ReturnSDOIf this element is set to true the SDOs are returned per document if they are present.​​[true | false]
​ReturnSDO / returnPartialIf this element is set to true then partial SDO's are returned per document if they are present.​[true | false]

GetDocuments response

​Name​Description​Constraints
​OrderID​​​The OrderID sent by the customer.
​​​

​MinLength = 1

MaxLength = 80

​TransRef​String uniquely identifying the transaction in E-Signing.​NA
​OrderDescription​The sign order description as it was defined by the customer when inserting the sign order.​​Only present if provided when the order was inserted.
​OrderStatus​The status of the sign order.​[Active | CancelledByMerchant | Expired | RejectedBySigner | Complete | ExpiredByProxy | Failed | Deleted]​
​StatusNote​​A text note that explains the status of archival, signature and procuration checks, business certificate download and sealing of the order.

​Possible status notes:[ArchivalStatus = Pending | Ready | InProgress | Complete | Failed]

[SignAndProcuraVerificationStatus = Pending | Ready | InProgress | Complete | Failed]

[BusinessCertificateStatus = Pending | Ready | InProgress | Complete | Failed]

[SealStatus = Pending | Ready | InProgress | Complete | Failed]

​SearchHits​The number of DocumentResult elements returned. Will be 0 if the LocalDocumentReference in the request is not present in the specified sign order.​nonNegative Integer
​DocumentResults / DocumentResult​The result of the request. A DocumentResult is returned per search hit. See table below for details.​NA


 

DocumentResult

​Name​Description​Constraints
​DocumentStatus​The document status. ​​​[Active | Complete | Pending | Expired | RejectedBySigner | CancelledByMerchant | Deleted]
​LocalDocumentReference​​​A reference to a specific document as defined when inserting the sign order.

MinLength = 1

MaxLength = 100​

​Presentation / Title​​The title of the document as defined when inserting the sign order

​MinLength = 4

MaxLength = 60

​Presentation / Description​The description of the document as defined when inserting the sign order.

MinLength = 4

MaxLength = 240​

​DocType / PDF /B64DocumentBytesT​he PDF document as defined when inserting the sign order. ​NA
​DocType / Text / B64DocumentBytesThe text document as defined when inserting the sign order. ​NA
​DocType / XML / B64XMLBytes​The XML document as defined when inserting the sign order. ​NA
​DocType / XML / B64XSLBytes​The XSL of the document as defined by merchant in the sign order. ​NA
​SDO / B64SDOBytes​The SDO bytes of the generated SDONA​
SDO / ​IsPartial​The IsPartial value as defined in the GetDocuments request. ​[true | false]

Back to top

GetSignature

The GetSignature message is used to retrieve a signature from a sign order along with the OCSP and SSN of the signer if available.  

GetSignature.PNG 

​Name​Description​Constraints​
​OrderID​​​​The OrderID sent by the customer.
​​​

​MinLength = 1

MaxLength = 80

​LocalSignerReference​A reference to a specific signer as defined when inserting the sign order. The sign processes for this signer will be shown as the result.

​MinLength = 1

MaxLength = 100

LocalDocumentReference​​A reference to a specific document as defined when inserting the sign order.​

MinLength = 1

MaxLength = 100​

​StepNumber​This value points to a specific step number in the sign order. If set, only signatures corresponding to that step will be returned. ​NA

GetSignature response

​Name​Description​Constraints
​OrderID​​The OrderID sent by the customer.
​​

​MinLength = 1

MaxLength = 80


​TransRef​String uniquely identifying the transaction in E-Signing.​NA
​LocalSignerReference​​A reference to a specific signer as defined when inserting the sign order.

​MinLength = 1

MaxLength = 100

​LocalDocumentReference​​​A reference to a specific document as defined when inserting the sign order.​

MinLength = 1

MaxLength = 100​

​B64Signature​The entire signature by the defined signer and on the defined document.​NA
​B64OCSP​The OCSP (validation) request corresponding to the signature. ​NA
​SignerID / IDTypeUnique identifier of the signer if available.

​[SSN | RID ]

SSN: BankID (NO), BankID on mobile (NO), BankID (SE)

RID: NemID CodeFile (DK)

​SignerID / IDValue​The ID value. The returned value is dependent on the eID used in the signature.

SSN:<SSN value>

RID: CVR:<CVR value>-RID:<RID value>

Back to top

GetNotificationLog

The GetNotificationLog message returns information about all notifications that have been sent to the customer itself and to signers involved in the specified sign order.

GetNotificationLog.PNG 

​Name​Description​Constraints
​OrderID​​The OrderID sent by the customer.
​​​​

​MinLength = 1

MaxLength = 80

GetNotificationLog response

​Name​Description​Constraints
​OrderID​​​The OrderID sent by the customer.
​​

​MinLength = 1

MaxLength = 80


​TransRef​​String uniquely identifying the transaction in E-Signing.​NA
​SearchHits​The number of notifications sent for the specified sign order.​NA
​NotificationRecords​A list of all notifications sent for the specified sign order.​Only present if the number of hits is one or higher.
​NotificationRecords / NotificationRecord​A notification sent by E-Signing. See the table below for details.​NA


 

NotificationRecord

​Name​Description​Constraints
​Recipient​Identifies the recipient of the notification. This is either the E-Signing customer or the signer. ​NA
​Recipient / MerchantIDRef​The customer's MerchantID. This indicates that the notification was sent to the customer.
​Recipient / LocalSignerReference​The reference to a signer in the sign order. This indicates that the notification was sent to this signer.

​MinLength = 1

MaxLength=100

​Channel / ChannelType​The channel for the notification. ​[Email | SMS | XMLService]
​Channel / EndPoint​This value is the channel value. It is the email address if the channel used is e-mail, the phone number if the channel is SMS or the HTTP address of the XML retriever if the channel is XMLService. ​NA
​Trigger​This value gives information about what triggered this notification.​[OnOrderCancellation | OnOrderCompletion | OnOrderRejection | OnOrderExpiration | OnStepExpiration | OnStepCompletion | OnStepReady | OnSignProcessRejection | OnSignProcessExpiration | OnSignProcessCompletion | OnSignProcessReady | OnReminderEvent | OnOrderFailed]
​NotificationStatusThis value gives information about the status of this notification.​[Sent | Failed]
​NotificationSentTimeThis value has two meanings. ​If the notification status is Sent then the time represents when it was sent or if the status is Failed then the time indicates when the last notification attempt failed.​NA
​StepNumberThis value is populated if the notification is triggered by a status change of either a step or a sign process and it is set to the step number of the step.  
​LocalDocumentReferenceThe local document reference is given if the notification was triggered by a status change of a sign process.

​MinLength = 1

MaxLength=100

Back to top