How to create a transaction with api generated fields

How-to create a transaction with api generated fields

In this how-to we describe how you can create a transaction with fillable form fields on a PDF that isn’t prepared in any way. This is different compared to How-to create a transaction with fillable form fields where you were required to use a PDF which already has all the form fields embedded in the PDF.

Create a transaction

First you will have to create a transaction. We’ll use the same flow as in How-to start a multi document transaction.

POST /api/transaction/

Example

curl \
-H "Authorization: APIKey {usertoken here}" \
-H "Application: APPKey {appkey here}" \
	-H "Content-Type: application/json" \
	-d '{
	  "Signers": [
		{
		  "Email": "user@example.com",
		  "RequireScribble": true,
		  "SendSignRequest": true,
		  "SignRequestMessage": "Hello, could you please sign this document? Best regards, John Doe",
		  "DaysToRemind": 15,
		  "ScribbleName": "John Doe",
		  "ScribbleNameFixed": false
		}
	],
	  "SendEmailNotifications": true
	}'
	https://api.signhost.com/api/transaction/

And you should receive a reply with at least the following content:

{
	"Id": "SomeTransactionId",
	"Status": 5,
	"Signers": [
		{
		   "Id": "SomeSignerId",
		   "Email": "user@example.com",
		   "RequireScribble": true,
		   "SendSignRequest": true,
		   "SignRequestMessage": "Hello, could you please sign this document? Best regards, John Doe",
		   "DaysToRemind": 15,
		   "ScribbleName": "John Doe",
		   "ScribbleNameFixed": false
		}
	]
}

• Success 200
• Success 201

The id SomeTransactionId is the transactionId and you will need this in your followup requests.

Add file meta data to transaction

PUT /api/transaction/:transactionId/file/:fileId

The following example creates two formset definitions. The first is named SampleFormset and contains 2 single line text fields and 1 signature field. The second SecondSigner only contains a signature field but is not used. We do recommend to use a width of 140 and a height of 70 for signature fields.

{
	"DisplayName": "Your personal contract",
	"Signers": {
		"SomeSignerId": {
			"FormSets": [ "SampleFormset" ]
		}
	},
	"FormSets": {
		"SampleFormset": {
			"AddressLine1": {
				"Type": "SingleLine",
				"Location": {
					"Search": "Address line 1",
					"Left": 100
				}
			},
			"AddressLine2": {
				"Type": "SingleLine",
				"Location": {
					"Search": "Address line 2",
					"Left": 100
				}
			},
			"SignatureOne": {
				"Type": "Signature",
				"Location": {
					"Right": 10,
					"Top": 10,
					"PageNumber": 1,
					"Width": 140,
					"Height": 70
				}
			}
		},
		"SecondSigner": {
			"Signature-2": {
				"Type": "Signature",
				"Location": {
					"PageNumber": 2,
					"Width": 140,
					"Height": 70
				}

			}
		}
	}
}

The FormSets array in the Signers/SomeSignerId should reference one or more keys in the FormSets dictionary. A FormSet should be unique within a transaction. If you provide a duplicate formset key we will overwrite the old one with the new one.

Field types

You can create various field types. We have the following field types available at the moment:

Check

When you specify the field type Check there is an additional value property you can set. The value property specifies the checked value of a checkbox. This does not specify the label of the checkbox.

For example:

{
	"UserAgrees": {
		"Type": "Check",
		"Value": "I agree",
		"Location": { "Search": "user_agree" }
	}
}

Field Location

The Location object determines where the field should be placed. You have the following options:

You are only required to provide the properties you want and leave the other properties away. In the simplest scenario you can only provide a value for Search.

Example

curl \
-H "Authorization: APIKey {usertoken here}" \
-H "Application: APPKey {appkey here}" \
	-H "Content-Type: application/json" \
	-XPUT \
	-d '{
		"DisplayName": "Your personal contract",
		"Signers": {
			"SomeSignerId": {
				"FormSets": [ "SampleFormset" ]
			}
		},
		"FormSets": {
			"SampleFormset": {
				"SignatureOne": {
					"Type": "Signature",
					"Location": {
						"Search": "{{Signer1}}"
					}
				},
			}
		}
	}' \
	https://api.signhost.com/api/transaction/SomeTransactionId/file/Contract.pdf

The response will tell you that it is awaiting the actual document.

Add the actual file to transaction

PUT /api/transaction/:transactionId/file/:fileId

Example

curl \
-H "Authorization: APIKey {usertoken here}" \
-H "Application: APPKey {appkey here}" \
	-H "Content-Type: application/pdf" \
	-XPUT \
	-T Contract.pdf \
	https://api.signhost.com/api/transaction/SomeTransactionId/file/Contract.pdf

• Success 201
• Success 204

We are looking into combining the meta data and the file contents into one API call

Start the transaction

PUT /api/transaction/:transactionId/start

Example

curl \
	-H "Authorization: APIKey {usertoken here}" \
	-H "Application: APPKey {appkey here}" \
	https://api.signhost.com/api/transaction/SomeTransactionId/start

Success 200

When all files are uploaded you can tell signhost to start the transaction.