Particeep

How to generate contracts

This section will cover one of the two steps needed to dematerialize a contract: Dynamic Generation

If your interest is for the second step, being the signature of the document, you can skip this and go to the how to sign a document section.


1 - About

When serving online contracts, we want it to be different for every User.

For example, in a subscription form ; the number of shares, the share's price, the payment method, the idendity of the investor and many other information will be different for every User.

So, with a single document and the information about the subscription, how can I create a custom contract for every User?

The Document Generation module of the Particeep's API has the answer to this question and the rest of this documentation will explain it in details.

It is very important to note that the document generation module of the API only works with a docx document as input and will create a pdf document.
Any other type of document provided as input will result with an error.


2 - Prerequisites

First of all, we need a document that will be the basis of all generated contracts and any information that can be used.

Gathering information can be done by yourself OR you can use other Particeep's API modules such as Forms to help you in this matter.

As for the document, for it to render custom information, we will be using merge fields.


3 - Merge fields

Merge fields are a basic feature proposed by most of the text editors such as Word. They are dynamic values. This means that they do not have a fixed value but rather will use injected variables.

Basic merge fields will take this form: $[variable_name] (eg. $first_name)

For the rest of this documentation, we will use this document as a basis:

Particeep Contract basis


4 - Generating the pdf document

In order to generate the contract, we have to send the variables to be used by the merge fields.

This is when calling our API get in the game.

We will need to send a POST request on /v1/document-generation with the following information:


			{
		"url": "https://api.particeep.com/document/946c01d2-d788-4253-be4e-f0ccc8752d68",
		"params_str": {
			"first_name": "John",
			"last_name": "Doe",
			"city": "London",
			"date": "12-18-2017"
		}
	}
		
Note that the url used in this example is the url of the previously linked document. You can use any url as long as it is an accessible docx document.

The result of this request will be our pdf contract:

Particeep Contract for John Doe


5 - Generating and uploading

If you are also using other modules of our API such as Document and User, we provide another endpoint that lets you upload the generated pdf document.

The endpoint can be accessed with a POST request on /v1/document-generation/upload/[owner_id] with the following information:


			{
		"url": "https://api.particeep.com/document/946c01d2-d788-4253-be4e-f0ccc8752d68",
		"params_str": {
			"first_name": "John",
			"last_name": "Doe",
			"city": "London",
			"date": "12-18-2017"
		},
		"name": "Particeep Contract for John Doe",
		"description": "This is the generated Particeep Contract for John Doe.",
		"path": "/documents/contracts/John Doe/"
	}
		
The server will respond with the information of the created Document.


6 - Advanced information

When creating your docx document with merge fields, you might need to use if conditions or for loops.
Here is the syntax for both of these:

If condition

For loop


7 - Advanced endpoint usage

This section will explain how to send Json value to the Document Generation module instead of plain strings.

In order to allow that, we implemented our special Object extractUtils. This object is set up with different methods depending on the type of the value that you want to extract from your Json values.

Let's have an example with this docx document.

Here is the information to send to the document-generation endpoint:


			{
		"url": "accessible document's url (must be a docx)",
		"params_obj": {
			"user": {
				"first_name": "Paul"
			},
			"form": {
				"name": "Basic Form",
				"sections": [
					{
						"name": "Section One",
						"description": "The first section",
						"questions": [
							{
								"label": "What is your marital status?",
								"answers": ["married"]
							},
							{
								"label": "How many children do you have?",
								"answers": ["3"]
							}
						]
					},
					{
						"name": "Section Two",
						"description": "The second section",
						"questions": [
							{
								"label": "What are your hobbies?",
								"answers": ["sport", "cinema"]
							}
						]
					}
				]
			}
		}
	}
		
The result of this request will be a pdf document like this one.


Next steps

Now that you know how to generate documents, you may want to: