—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 7 minutes

Edit this page ↗

#PDF templating API's

PDF templating API's can be used to upload a PDF with fillable form template. Fill data into it the form and create unique PDFs for signing.

Here’s a quick run through of the APIs—

  1. Upload document—Upload a PDF with fillable form. You get template id and form fields in reponse.
  2. Render template-Render the template with the data to be filled in the form. Returns a document Id. (Can be skipped)
  3. Create signature request-Create a signature request with the rendered template. Get singing link in response.
  4. Update template-update the form fields/template doc with template id.
  5. Get template-get template doc and form fields with the template id.

The render template API can be skipped and task of rendering the document can be moved to the create signature request API itself, by passing the form fields and templateId to the create signature request API.


Here are the URLs you would need for these APIs—

  • Sandbox—https://dg-sandbox.setu.co
  • Production—https://dg.setu.co
  • Headers—Contact Setu for providing the credentials required to successfully call Setu APIs. This contains:
    • x-client-id
    • x-client-secret
    • x-product-instance-id

#Upload PDF template

Call this API to upload the document that has to be signed. The document and the document name would be passed as a multipart/form-data upload of the files and name parameters respectively.

Setu has processed your request successfully.

Request
POST /api/documents 
 
payload= { 
    "name": "account opening form" 
 } 
 
files= [ 
  ("document", ("aof.pdf", open("/Users/path/Aof.pdf", "rb"), "application/pdf")) 
]
Response

You will get a unique id which is the temaplateId from Setu for render template/signature request creation.

 {
  "template_id": "2976a4f8-84a5-4f1f-bc49-4c4a71c07900",
  "name": "account opening form",
  "form_fields": {
    "text": {
      "dob": "",
      "city": "",
      "place": "",
      "state": ""
    },
    "check_boxes": {
      "#c.gender.F": "",
      "#c.gender.M": "",
      "#c.gender.U": "",
      "#c.income.a": "",
      "#c.income.b": "",
      "#c.income.c": ""
    },
    "images": {
      "#i.bank_proof": ""
    }
  },
  "traceId": "1-67e51c57-74fbcff84f4ea1ee6cb27e27"
}

#Render template request

Render a template by filling form data. Create a filled pdf file by passing in the form field data and the template id in the request. You get an document id in response, which you can use to create the signature request.

Render template functtionality can also be clubbed up with create signature request.


Here is a quick description of the values required to call this API—

  • template_id the template id of the document, which you get from the Upload template API response.
  • form_fields The form fields with value to be filled in the template pdf

The image fields should be passed as base64 encoded string of jpeg/jpg.

Setu has processed your request successfully.

Request
POST /api/documents 
 
payload= {
  "template_id": "2976a4f8-84a5-4f1f-bc49-4c4a71c07900",
  "form_fields": {
    "text": {
      "dob": "1998",
      "city": "Delhi",
      "place": "Chanakyapuri",
      "state": "Delhi"
    },
    "check_boxes": {
      "#c.gender.F": "/Yes",
      "#c.gender.M": "",
      "#c.gender.U": "",
      "#c.income.a": "",
      "#c.income.b": "/Yes",
      "#c.income.c": ""
    },
    "images": {
      "#i.bank_proof": "jpg image's base64 string"
    }
  }
}
Response

You will get a unique id which is the temaplateId from Setu for render template/signature request creation.

 {
    "documentType": "application/pdf",
    "downloadUrl": "https://s3-link-goes-here.com",
    "id": "d784d36c-88c8-4670-b320-d164cad73d8c",
    "name": "account opening form"
}

#Create signature request

You can use the render template feature with our create signature API or pass the document id returned from render template API. The create request API can be used either with a flexible configId or generic sign placement keys like lower-left, upper-right etc.

Create request using documentId (you can also use configId)

Setu has processed your request successfully.

Request with documentId
{
                "documentId": "d784d36c-88c8-4670-b320-d164cad93d8v",
                "redirectUrl": "http://setu.co",
                "reason": "test",
                "signers": [
                    {
                    "identifier": "7042484922",
                    "displayName": "Rahul Roy",
                    "geoCoordinate": "123.45, 56.7",
                    "location": "patiala punjab",
                    "signerNo": 1,
                    "signature": {
                                "height": 60,
                                "onPages": [
                                    "1"
                                ],
                                "position": "bottom-right",
                                "width": 180
                            }
                    
                    }
                ]
            }
Response
 {
                "documentId": "54879ac9-18ed-424c-8191-56f24b8e89e0",
                "id": "1ef895e5-a2d6-46a1-a415-297a5fe631b1",
                "reason": "test",
                "redirectUrl": "http://setu.co",
                "signers": [
                    {
                        "birthYear": "None",
                        "displayName": "Rahul Roy",
                        "errCode": null,
                        "id": "d54fe2d2-77b6-44aa-a216-6830fb9d043f",
                        "identifier": "7042484922",
                        "location": "patiala punjab",
                        "signatureDetails": null,
                        "status": "pending",
                        "url": "http://localhost:8000/signature/preview?requestId=1ef895e5-a2d6-46a1-a415-297a5fe631b1&signerId=d54fe2d2-77b6-44aa-a216-6830fb9d043f"
                    }
                ],
                "status": "sign_initiated",
                "traceId": "a6e8af2b-31d6-454d-9325-009f2c144bd3"
            }

#Update the PDF template

This api can be use to update the pdf template. The update API will behaves in this fashion:-

  1. if just document is send in request then a new transformed form fields json will be created which will overwrite the existing form fields json.
  2. If just form fields are sent, then existing form fields json will be updated with new form fields.
  3. If both the form fields and template document are sent, then existing form fields json will be updated with new form field, request's doc would be ignored.

This api uses verioned updates. You can use the get API to view older verions. While singing/rendering document just the latest version can be used.

Setu has processed your request successfully. You will get signing link in response.

Request
POST /api/documents 
 
payload= { 
    "name": "account opening form" 
    "form_fields": {
        "text":{
                "dob": "", 
                "city": "", 
                "nominee3_guardian_address": "" 
                }, 
        "check_boxes": {
                "#c.raa.r1": "", 
                "#c.raa.r2": "" 
                }, 
        "images": { "#i.bank_proof": ""} 
    } 
 
files= [ 
  ("document", ("aof.pdf", open("/Users/path/Aof_new.pdf", "rb"), "application/pdf")) 
]
Response

You will get the updated form_fields and the doc url and version_no.

 {
    "template_id": "8bba0bea-0c63-4eb2-9da9-11b5114b579b",
    "template_doc_url": "http://localhost:4566/dg-uat-persistent/b186f03d-3db2-4bf1-b75e-4b6fde0e27d8/69e1d94f-ece8-4536-8b29-e737b5b2b85a.pdf",
    "name": "aof_groww",
    "version_no": 2,
    "form_fields": {
        "text": {
            "dob": "",
            "city": "",
            "bo_id": ""
        },
        "check_boxes": {
            "#c.gender.F": "",
            "#c.gender.M": "",
            "#c.gender.U": "",
            "#c.income.a": ""
        },
        "images": {
            "#i.bank_proof": ""
        }
    },
    "traceId": "ad143efa-d109-41ae-981f-14c673a7a48e"
}

#Get the PDF template

Call this API to get a pdf template.

Request

Pass the template id and version No as a URL parameter. If the version no is not passed, the latest version will be returned.

GET /api/templates/:id/:version_no
Response
{
    "template_id": "8bba0bea-0c63-4eb2-9da9-11b5114b579b",
    "name": "aof groww",
    "form_fields": {
        "text": {
            "dob": "",
            "city": "",
            "bo_id": "",
            "dl_no": "",
            "dp_id": "",
            "place": "",
            "state": ""
        },
        "check_boxes": {
            "#c.raa.r1": "",
            "#c.raa.r2": "",
            "#c.gender.F": "",
            "#c.gender.M": "",
            "#c.gender.U": ""
        },
        "images": {
            "#i.bank_proof": ""
        }
    },
    "version_no": 1,
    "template_doc_url": "http://localhost:4566/dg-uat-persistent/b186f03d-3db2-4bf1-b75e-4b6fde0e27d8",
    "traceId": "1bd6877f-df76-4930-8014-94595e358485"
    }

Was this page helpful?