Creating a new signature request

Signature request is a container for documents and their signatories. A basic process follows roughly this outline:

1. Retrieve a token from login
2. Create a new signature request container
3. Upload documents
4. Attach the documents to signature request
5. Update the status of signature request.

After these steps, a new signature request has been created and the workflow is taken over by the service.

Walkthrough

1. Retrieve a token from login

In order to be able to make the required calls to the services, first we need to request the token that will get attached to all the concurrent requests.

Request

Request payload contains the login credentials, along with the tenantid against which the login attempt is made.

POST https://api-test.teliasign.com/identity/login
{
    "login": "john.doe",
    "password": "doeisme",
    "tenantid": "00000000-0000-0000-0000-000000000000"
}
Ocp-Apim-Subscription-Key: {subscription-key}

Response

Response is a simple structure, containing only a single element with the token value within it.

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI6ImpvaG4uZG9lQHZpbmNpdHNpZ24uY29tIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy91c2VyZGF0YSI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSIsInJvbGUiOiJCYXNpYyB1c2VyIiwiaHR0cDovL3ZpbmNpdHNpZ24uY29tLzIwMTYvMTAvaWRlbnRpdHkvY2xhaW1zL3RlbmFudCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImF1ZCI6Imh0dHA6Ly93d3cuamF2ZXJkZWwuZmkvIiwiZXhwIjoxNDg2Njk1NjI3LCJuYmYiOjE0ODY2OTM4Mjd9.nEw_5BiSJS3wjOjtTVvTRyH56bt4qBJOv7o9f9Z93VU"
}

2. Create a new signature request container

In order for us to perform the rest of the required steps, we will need a signature request container to which we can do the associations to. We can give some basic information about the request, along with the intended recipients.

Request

POST https://api-test.teliasign.com/signing/signaturerequest
Authorization: Bearer {Received token value from step #1}
Ocp-Apim-Subscription-Key: {subscription-key}

{
    "subject": "Contract #1231",
    "creatorId": "00000000-0000-0000-0000-000000000000",
    "creatorName": "[text]",
    "expirationDate": "2019-12-01T00:00:00.000Z",
    "formOrderCoverLetter": "[text]",
    "departmentId": "00000000-0000-0000-0000-000000000000",
    "signatureRequestTypeId": "3246C579-4FF4-4B9E-849B-B2348E6179C8",
    "signatureRequestTemplateId": "00000000-0000-0000-0000-000000000000",
    "externalReference": "[text]",
    "readingAuthenticationStrength": "high",
    "signingAuthenticationStrength": "high",
    "languageCode": "en-GB",
    "status": 0,
    "signatories": [
        {
            "firstName": "John",
            "lastName": "Doe",
            "email": "john.doe@teliasign.com",
            "mobilePhone": "+358123456789",
            "isMandatory": true,
            "authenticationAreaCode": "FI",
            "personalIdentifier": "[text]",
            "isPersonalIdentifierHashedInSignature": true,
            "signatoryGroupSigningOrder": 0,
            "isBundleSignatureRequests": 0
        }
    ],
}

Note: The status value 0 indicates that the signature request is in a draft stage. When the status is draft, it will not get processed and can be modified freely.

Note: The readingAuthenticationStrength and signingAuthenticationStrength fields can be set to high, medium or low. The readingAuthenticationStrength field can be also set to none value additionally which means no authentication is needed to read the signing documents. The matching authentication methods for the values high, medium and low can be and are configured for the particular tenant. The signingAuthenticationStrength value can be the same but cannot be lower than readingAuthenticationStrength one. The possible strength options will depend on the configuration of the customer instance.

Note: When isPersonalIdentifierHashedInSignature is set to true then the personal identifier of signatory will be hashed in the signed document.

Note: When the signatory property isBundleSignatureRequests is set to true then all signature requests that the specific signatory belongs to and are in an open state (including the current one) are bundled together into one bundled request.

The signatory will receive a message with the bundled request.

The bundled requests allows the signatory to sign multiple signature requests at once.

Every time a new bundled request is created all open signature requests will be included.

A signatory can also sign individual signature requests even though they are included in a bundled request.

A new bundled request is automatically created when an individual signature request (belonging to a bundle) is signed, rejected, canceled or has expired. A bundled request will stop working when one of the contained signature requests is signed individually.

The isBundleSignatureRequests default value is false.

Response

The response will largely contain much of the same values as in the request, but it will also give us the id value which is required for next operations.

{
  "id": "014A79E7-75DF-4D93-AE6F-766D020B5449",
  "subject": "Contract #1231",
  "departmentId": "00000000-0000-0000-0000-000000000000",
  "creatorId": "00000000-0000-0000-0000-000000000001",
  "creatorName": "John Doe",
  "status": "Draft",
  "languageCode": "en-GB",
  "expirationDate": "2017-12-01T00:00:00.000Z",
  "creationDate": "2017-04-10T04:13:40.873",
  "modifiedDate": "2017-04-10T04:13:40.873",
  "statusDate": "2017-04-10T04:13:40.873",
  "formOrderCoverLetter": "[text]",
  "signatureRequestTypeId": null,
  "signatureRequestTemplateId": null,
  "readingAuthenticationStrength": "high",
  "signingAuthenticationStrength": "high",
  "externalReference": "[text]",
  "signatories": []
}

Note: The signatories field value is not returned back by default. The expandParameter field in creation request can be used to specify the fields to be returned. The format of the expandParameter value is comma separated string, e.g. "expandParameter": "signees,someField1,someField2".

3. Upload documents

Request

POST https://api-test.teliasign.com/storage/document?validateforsigning=true
Authorization: Bearer {Received token value from step #1}
Ocp-Apim-Subscription-Key: {subscription-key}

{
    "externalReferenceId":"00000000-0000-0000-0000-000000000000",
    "signed":false,
    "base64File":"JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0...",
    "name":"The greatest story ever told.pdf"
}

Note: The externalReferenceId field should contain the SignatureRequestId received during the creation of the signature request container.

Note: The file contents need to be base64 encoded and inserted into the base64file field.

Note: Optional query parameter validateforsigning can be used to enforce document validity for signing upon upload. When using this parameter, basic checks are performed, such as: is the document a valid pdf, has it already been signed etc. When uploading attachment then this parameter can be omitted or set to false.

Response

{
  "name": "The greatest story ever told.pdf",
  "externalReferenceId": "00000000-0000-0000-0000-000000000000",
  "blobConnectionId": "8a844a80-3e92-4e95-9b26-c6ae2022cace",
  "path": "Main/",
  "type": "Document",
  "creationDate": "2017-04-10T04:13:40.873",
  "modifiedDate": "2017-04-10T04:13:40.873"
}

4. Attach documents to signature request

Next step is to attach the uploaded document into the created signature request. For this, you need the document id from step #3. Get the value from blobConnectionId field, and use it for documentUri value.

Request

POST https://api-test.teliasign.com/signing/signaturerequest/{SignatureRequestId}/document
Authorization: Bearer {Received token value from step #1}
Ocp-Apim-Subscription-Key: {subscription-key}

{
    "documentTypeId": "6283829A-3508-45D9-A240-3DC27FFD8B09",
    "title": "The greatest story ever told.pdf",
    "fileName": "The greatest story ever told.pdf",
    "creatorId": "8556D663-B36D-4920-9BCE-DB05DD7F146F",
    "creatorName": "John Doe",
    "documentUri": "8a844a80-3e92-4e95-9b26-c6ae2022cace"
}

Note: The document type is used to distinguish documents by their purpose. See the mandatory field documentTypeId. In the example we use the General document type, which has the id of 6283829a-3508-45d9-a240-3dc27ffd8b09. The Attachement document type has id db8d644f-f32f-4fda-ada9-34e8296d54d4.

Response

{
  "id": "39a1d7cb-5b42-4c9d-ba80-8426277b8e42",
  "documentTypeId": "6283829a-3508-45d9-a240-3dc27ffd8b09",
  "signatureRequestId": "014A79E7-75DF-4D93-AE6F-766D020B5449",
  "title": "The greatest story ever told.pdf",
  "fileName": "The greatest story ever told.pdf",
  "tenantid": "00000000-0000-0000-0000-000000000000",
  "creatorId": "8556d663-b36d-4920-9bce-db05dd7f146f",
  "creatorUserName": "John Doe",
  "documentURI": "8a844a80-3e92-4e95-9b26-c6ae2022cace",
  "formTemplateId": null,
  "parentDocumentId": null,
  "creationDate": "2017-02-10T05:21:47.323",
  "modifiedDate": "2017-02-10T05:21:47.323"
}

5. Update the status of signature request.

Once all the wanted elements are in place, the signature request can be sent forward to signatories. This can be achieved by updating the status of the signature request from draft into open.

NOTE: When creating a form order then the status needs to be changed from "draft" to "pending".

Request

PATCH https://api-test.teliasign.com/signing/signaturerequest/{SignatureRequestId}
Authorization: Bearer {Received token value from step #1}
Ocp-Apim-Subscription-Key: {subscription-key}

{
    "status": "Open"
}

Response

{
  "status": "Draft",
  "statusDate": "string"
}

Note: The signature request status field can aquire the following values

Code	Name	Description
0	Draft	Signarute requst will not get processed and can be modified freely.
1	Open
2	Closed
3	Canceled
4	Rejected
5	Expired
6	Rejecting	Temporary state during which ESB performs.
7	Canceling	Temporary state during which ESB performs.
9	Error	Not yet used.
10	Unknown	Not yet used.
12	Pending	Indicates open form order. The status is changed to Open (1) when filled form order is submitted back by customer and signature request of it is sent.

Note: The signee status field can aquire the following values

Code	Name
0	New
1	Sent
2	Approved
3	Canceled
4	Rejected
5	Expired
6	Rejecting
7	Canceling
8	RejectedByExit
9	Error
10	Unknown