Send document

Endpoint

post

https://app.paksign.pk/api/documents/send

Overview

Sending a document requires some homework. Here are the three concepts you need to be familiar with;

Asset

An Asset is a page of your document. Eg, if you upload a document with 2 pages, you'll get 2 assets back from the API, each with a unique key.

Signer

A document needs to have at least one Signer before you can send it out for signing.

This can be yourself or anybody else. These people will fill out the elements you've added to your document and then click Sign.

Element

An Element is an item that your signer needs to fill out before they can sign the document. Eg, their name, signature, date, etc.

These are assigned to a signer and placed on an asset.

First, you need to assemble a list of signers. You need their name and email address, and assign a unique id to each. Internally, Paksign uses nanoid but you can use any namespaced, collision-proof random generator, like uuid v5.

Let's say your signers look like this;

signers.json

[
  {
    "id": "abc",
    "name": "Michael",
    "email": "michael@example.com"
  },
  {
    "id": "def",
    "name": "Jim",
    "email": "jim@example.com"
  },
  {
    "id": "ghi",
    "name": "Dwight",
    "email": "dwight@example.com"
  }
]

Elements

Second, you need to create your elements and put them on assets and assign to the signers.

Let's say your 2-page document after uploading to Paksign and converted to assets look like this;

assets.json

[
  {
    "key": "c123",
    "height": 800,
    "width": 600
  },
  {
    "key": "c456",
    "height": 800,
    "width": 600
  }
]

You now need to calculate where to put the elements. For the placement, we limit the height of the document to the following;

For portrait mode: 1200px
For landscape mode: 600px

And calculate the width while keeping the asset ratio intact. Eg, for a 600px × 800px asset, the dimensions will change to 900px × 1200px.

Now, you can figure out where the elements would go. This would depend on the contents of your document. Each element has a top and left property, which determines where they would be placed on the asset. Eg, if signer Michael needs to sign on the second page of the document towards the end, it would look something like this;

elements.json

[
  {
    "assetKey": "c67890", // asset key of the second page
    "id": "ZeFrr7yYXIh", // some unique value for each element
    "label": "Please sign here", // a label visible to the signer with some helpful text
    "left": 20, // position from the left side of the page
    "signerId": "abc", // signer id you've previously generated for _Michael_
    "top": 1000, // position from the top side of the page
    "type": "signature" // to show a signature box, but can be any of the others
  }
]

Request

Field	Description	Type	Required
`workspaceId`	Your workspace id	`number`	Yes
`title`	Document title	`string`	Yes
`slug`	Document slug from upload	`string`	Yes
`source`	Document source key from upload	`string`	Yes
`files`	Document assets from upload	`Asset[]`	Yes
`signers`	Document signers	`Signer[]`	Yes
`elements`	Signer elements	`Element[]`	Yes
`meta`	Document metadata	`object`	No

Response

Field	Description	Type
`document`	Document object	`Document`

Example

This example is written in TypeScript and assumes you're using axios.

send-document.ts

// create payload
const payload: Request = {
  // ...
}
// send the request
const { data } = await axios.request<Response>({
  url: '/api/documents/send',
  method: 'post',
  data: payload,
  headers: {
    Authorization: 'Key YOUR_API_KEY',
  },
})