Creating and Applying Layouts to PDF Documents

0 votes


I am new to the OneSpan sandbox and REST APIs/.NET SDK

I have the following scenario and I'm using some CodeShare samples to piece this together:

1. Retrieve a PDF without embedded signature blocks from our database via one of our own REST APIs -- Completed and works

I also tried the document extraction example but that appears that the PDF must have signature blocks embedded in it.  Is this correct?

2. Create a layout programmatically via either REST API or .NET SDK. From what I understand, this requires an existing package.
So do I need to create and send a package first with the previously downloaded PDF file?
I can create a Layout from the UI manually but would prefer to create it programmatically.

3. Retrieve all layouts or a matching layout via either REST API or .NET SDK.  REST API appears to return one rather than a JSON array of Layouts. The count is correct in the JSON object. .NET SDK retrieves all layouts to be matched to either the PDF file or a package.

4. Apply the correct layout to the PDF file via either REST API or .NET SDK.  I can retrieve one layout but it does not appear to apply correctly to the package of interest. What is the best way to match layout to package documents, i.e do the layout names need to match the document name for the layout being applied?

5. Send the package to be signed.

I have attached my POC sln for actual code usage.

Here is the "formatted" output from the POC:

Request URI = http://<server stuff>/api/document/5/35902/content/?format=2&logActivityType=4

{"Layout id":"toCMBtiO8eIh0t8FINTxkik9_F4="}
{"Layout id":"x3WBbO3QWGPusDN7rzUAaqibnVg="}

1: sampleAgreement _cqYupmiKucgroIB8vg_QkteDZ0=
2: FranchiseAgreement vDgkDv24tQNrC9xVOLBNCs_3sho=

Layout: sampleAgreement, LayoutId = _cqYupmiKucgroIB8vg_QkteDZ0=, DocumentId = 1d31f7c2548808dc8966b7ac755be4d39d0c39d9338d9f97
<html><head><title>Error</title></head><body>Bad Request</body></html>

Layout sampleAgreement (s/b FranchiseAgreement) applied to packageId {"id":"toCMBtiO8eIh0t8FINTxkik9_F4="}
<html><head><title>Error</title></head><body>Bad Request</body></html>

I am looking for best approach/practice to achieve the steps above.

Thank you for any insights or help you may be able to provide.

Thank you,


Reply to: Creating and Applying Layouts to PDF Documents

0 votes

Hi cdean,


To answer your questions inline:
1. Document extraction methods (Document Extraction, Text Tags Extraction, or Position Extraction) required you to add either Adobe forms or certain text (in text tag syntax) to your PDF. 

2. Yes, you need to create a package first, but no need to send it. So two steps to follow:
(1)create a draft package, with all signers and one document

(2)save layout with this API:
POST /api/layouts

   "name":"Layout 02",


"id" refers to the package id created in the first step

"name" is the layout name which is essential to locate this layout later

"visibility": could be "SENDER" or "ACCOUNT", determine whether other senders under the same account can retrieve and share to use this layout

"document" > "id" : assuming you are saving layout out of a package with multiple document, this is to define which document you want to save as layout.


3. You need two extra parameters to return multiple results:
GET /api/layouts?from={fromPage}&to={toPage}


4. To apply a layout, you need to invoke one of below two APIs, with either layout ID or Name:

POST /api/packages/{packageId}/documents/{documentId}/layout?layoutId={layoutId}


POST /api/packages/{packageId}/documents/{documentId}/layout?layoutName={layoutName}


This means you want to apply the layout with {layoutId} or {layoutName} to document {documentId} under {packageId}. Because layout only contains JSON of one document, there won't be a mismatch.

In terms of the signer match, OneSpan Sign system matches the role Name between your package and the layout. Signer(s) who doesn't have a match will be automatically added to your package.


Because I am off this week, so I may not be able to look closer to your code right now. I will bring it down for now because it contains your sensitive information and I will follow up with you next week when I am back.




Duo Liang OneSpan Evangelism and Partner Integrations Developer

Reply to: Creating and Applying Layouts to PDF Documents

0 votes

Thank you very much Duo_Liang.

It sounds like my sequence is correct in my mind...thanks for validating the process.
I have a couple of incorrect Api calls as well as jsonString replacements that need to be done. I will fix these.
I am very close.  I am getting a 404 when I try to apply the layout.
I will continue to work on getting the layout to match/find the document in the package.

Thanks again for your help and I look forward to hearing from you next week.
Enjoy the rest of your time off!


Thank you,


Hello! Looks like you're enjoying the discussion, but haven't signed up for an account.

When you create an account, we remember exactly what you've read, so you always come right back where you left off