5.8 Get Package Status
5.8.1 Description
Retrieves the current state of the package and its documents.
5.8.2 URL
https://[servername]:[port]/webportalapi/v3/packages/{id}/status
5.8.3 HTTP Method
GET
5.8.4 Template parameters
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
id | Required | Unique id for the signing package | String |
5.8.5 Response parameters
Parameter | Content / Description | Type |
---|---|---|
PackageName | Description for the Package shown to the eSignatures Portal user as file name. | String |
CreationTimestamp | Date and time when the package was created according to the server. Format is ISO 8601 date-time. E.g. 2018-01-23T12:34:00.000Z |
String |
Initiator | Initiator field of the package as it was passed in at creation time. | String |
ExpiryTimestamp | UTC formatted time at which the document expires. Can be null. | String |
ExternalPackageReference | Returns the external reference id of the package as it was passed in at creation time. | String |
F2FSigningUrl | Link to the package which allows to pick from all the signing session at once. | String |
PackageStatus | Status of the package as a whole: Draft Pending Finished Rejected Revoked Expired Failed Note: a package has the status Failed when a background operation has failed and left a message on the Poison Queue. |
String |
PackageDocuments | Details for each of the documents in the package. | Array of objects |
Stakeholders | Details for each of the persons which will interact with the package. | Array of objects |
Parameter | Content / Description | Type |
---|---|---|
PackageDocuments (array of object) | Details for each of the documents in the package | Array of objects |
DocumentId | Unique id of the document | String |
ExternalDocumentReference | Returns the external reference of this document as it was passed in through the Add document to package call. | String |
DocumentName | Name of the document | String |
DocumentType | Type of document within the package. Possible values: application/pdf or application/xml |
String |
Parameter | Content / Description | Type |
---|---|---|
Stakeholders (array of objects) | Details for each of the persons which will interact with the package. | Array of objects |
Type | Type of stakeholder: Person, PersonGroup, or ContactGroup. | String |
PersonGroupName | Name of the person group. Only returned if Type was set to PersonGroup in the request. | String |
ContactGroupCode | Code of the contact group. Only returned if Type was set to ContactGroup in the request. | String |
EmailAddress | Email address of the signer. | String |
ExternalStakeholderReference | External reference identifying this person in the external system. Note: when a package is reassigned, the ExternalStakeholderReference is transferred to the new assignee. |
String |
StakeholderId | Unique id Note: when a package is reassigned, the StakeholderId is transferred to the new assignee in a standard use case. When using complex signing scenario in which signer 1 is also signer 3, a new StakeholderId will be created for the new assignee who will become signer 1. |
String |
Actors | See below | Array |
Parameter | Content / Description | Type |
---|---|---|
Stakeholders => Actors (object) | Details of all steps to take. | Array of objects |
ActorId | Unique id for this combination of action, stakeholder and document. | String |
ActionUrl | URL that this person can open to interact with the package. This parameter is only used when Stakeholder Type is set to Person, or not passed at all. When the Stakeholder Type is set to PersonGroup or ContactGroup, the ActionUrl will be null. Instead, the different Urls sent to the different persons are listed in the ActionsUrls array. Exception: if the PersonGroup or ContactGroup only contains 1 person, the ActionUrl parameter will still be returned instead of the ActionUrls. |
String |
ActionUrls | Array of URLs that the different persons of the PersonGroup or ContactGroup can open to interact with the package. The ActionsUrls array is only used then the Stakeholder Type was set to PersonGroup or ContactGroup. Each person receives a unique URL only they can use. See the table below. |
Array of objects |
ActorStatus | Draft (package has status Draft) Inprogress (package is being signed) Available (ready for execution) Finished Rejected (signing cannot continue) Failed (signing has failed) Skipped (Initiator skipped the actor) |
String |
Type | Approver Signer Receiver |
String |
CompletedBy | The name of the end user who completed the action. This can only be properly filled when an authenticated signing method is used like BeId or Idin. Can be null, will never be present for a Receiver. |
|
CompletedTimestamp | Timestamp of the moment on which this action was completed. Format is ISO 8601 date-time. E.g. 2018-01-23T12:34:00.000Z Can be null, will never be present for a Receiver |
|
Reason | Returns the text entered by the person who changed the status of a package to a final state (e.g. a reject). Can be null, will never be present for a Receiver. |
String |
Locations | See table below. | Array of objects |
Parameter | Content / Description | Type |
---|---|---|
Locations (array of objects) | Represents a possible location for a signature. | Array of objects |
Id | Unique id for this location | String |
UsedSigningType | Returns the signing type that was used to sign the document. See section 9 for an overview of the available signing types. If no signing type was used (i.e. if the document isn’t signed yet), this parameter returns “null”. | String |
Parameter | Content / Description | Type |
---|---|---|
Stakeholders => Actors => ActionUrls (array of objects) | Array of URLs that the different persons can open to interact with the package. The ActionURLs array is only used when the Stakeholder Type was set to PersonGroup or ContactGroup. Each person receives a unique URL only they can use. Exception: if the PersonGroup or ContactGroup only contains 1 person, the ActionUrl parameter will still be returned instead of the ActionUrls. |
Array of objects |
EmailAddress | Email address of the person. | String |
Url | URL that this person can open to interact with the package. | String |
5.8.6 Example response
{
"PackageName": "package-docu1.pdf",
"Initiator": "signer@gmail.com",
"ExpiryTimestamp": null,
"ExternalPackageReference": "reference",
"F2FSigningUrl": "http://myserver/signinit?packageSignId=6bc402eb-6cbd-423a-bf00-1157e8d68f37&f2f=True",
"PackageStatus": "Pending",
"PackageDocuments": [
{
"DocumentId": "dc2691d8-e3c0-470b-9715-e55b489ea493",
"DocumentType": "application/pdf",
"ExternalDocumentReference": null,
"DocumentName": "docu1"
}
],
"Stakeholders": [
{
"Type": "PersonGroup",
"EmailAddress": null,
"ContactGroupCode": null,
"ExternalStakeholderReference": "stakeref",
"StakeholderId": "6b2cda0c-ab81-4984-9e16-159fe20d983f",
"Actors": [
{
"Type": "Signer",
"Reason": null,
"CompletedBy": null,
"CompletedTimestamp": null,
"Locations": [
{
"Id": "24ab070a-29e4-496e-9b79-e66c0edcced7",
"UsedSigningType": null
}
],
"ActorId": "2806f94d-2a45-4168-8667-cbd4ce4ce090",
"ActionUrl": null,
"ActionUrls": [
{
"EmailAddress": "john.smith@mail.com",
"Url": "https://MyURL.com"
},
{
"EmailAddress": "jane.jefferson@mail.com",
"Url": "https://HerURL.com"
}
],
"ActorStatus": "Available"
},
{
"Type": "Receiver",
"ActorId": "e3da1877-fac9-43c4-9949-bacef76718fa",
"ActionUrl": null,
"ActionUrls": [],
"ActorStatus": ""
}
],
"PersonGroupName": "APIGroup"
},
{
"Type": "Person",
"EmailAddress": "signer@gmail.com",
"ContactGroupCode": null,
"ExternalStakeholderReference": "3",
"StakeholderId": "490e242f-43c4-4bc0-a1b4-e2d67dc1fdac",
"Actors": [
{
"Type": "Receiver",
"ActorId": "0903c863-9197-4abf-93f4-694fddde9d99",
"ActionUrl": null,
"ActionUrls": [],
"ActorStatus": ""
}
],
"PersonGroupName": null
}
],
"CreationTimestamp": "2019-10-23T13:34:12Z"
}
5.8.7 Response codes
Response status code | Description |
---|---|
200 OK | The package was returned successfully. |
404 Not Found | The package with the specified id could not be found. |
409 Conflict | The package with the specified id was made with an old version of the api. |
5.8.8 Error codes
HTTP Code | Code |
---|---|
404 | Package.NotFound |
409 | Package.ApiVersionMismatch |