Adding an signer after package is created

Hi Srini, Yes, you can add a signer to a package as long as the package is in DRAFT status. The API to achieve this is: HTTP Request

POST /api/packages/{packageId}/roles

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
  "id": "Signer5",
  "type": "SIGNER",
  "signers": [
    {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Smith",
      "id": "Signer5"
    }
  ],
  "name": "Signer5"
}

However, if your document contains extraction tags like text tags or document extraction, since the fields can only be extracted at the moment when the document was uploaded, the fields won't be applied to later added signers. In this case, you'd use a placeholder signer with the Role name, then update this signer with detailed signer information (first/last names, title, company, signer authentication, etc).

PUT /api/packages/{packageId}/roles

Duo

Thanks Duo. So if I understand this correctly all the signature anchor tags need to go in when the document is added. Modify package cannot add additional signature tags like "extractAnchor": { "text": "Date", "index": 0, "width": 300, "height": 24, "anchorPoint": "BOTTOMRIGHT", "characterIndex": 3, "leftOffset": 2, "topOffset": 10 } so the suggestion is to create dummy roles and later update it with actual data for the user..?

Hi Srini, That's correct, the doc engine will only process the tags/anchors once when the document get uploaded and you can't add extra metadata later on. And as you mentioned, the recommended way is to use dummy roles as placeholders and build up a fully baked document when upload. Duo

Got it. Thanks.

I am not able to figure out how to do a placeholder signer while creating a package...? Can you please provide a sample?

Hi Srini, The only difference between placeholder signer and a genuine signer is: placeholder omits the "signers" node in "roles" array, which was left to be updated in future. So if you applied this payload (two roles and one document) and go check your web portal, you will see the effect:

{
  "roles": [
    {
      "id": "Role1"
    },
    {
      "id": "Role2"
    }
  ],
  "documents": [
    {
      "approvals": [
        {
          "role": "Role1",
          "fields": [
            {
              "page": 0,
              "top": 100,
              "subtype": "FULLNAME",
              "height": 50,
              "left": 100,
              "width": 200,
              "type": "SIGNATURE"
            }
          ]
        },
        {
          "role": "Role2",
          "fields": [
            {
              "page": 0,
              "top": 300,
              "subtype": "FULLNAME",
              "height": 50,
              "left": 100,
              "width": 200,
              "type": "SIGNATURE"
            }
          ]
        }
      ],
      "name": "Test Document"
    }
  ],
  "name": "Example Package",
  "type": "PACKAGE",
  "language": "en",
  "emailMessage": "",
  "description": "New Package",
  "autocomplete": true,
  "status": "DRAFT"
}

Duo

Thanks again. So the placeholder can only be done if we set it as "DRAFT" status right? And the emails won't be sent until the status is set to "SENT"?

Hi Srini, Yes, you can't send a package with placeholder signer exists. Duo

ahh .. ok. But we want to get the signature out as and when the user is available for sign. BTW, we are using API and will be relying on callback which will give us the signing URL... so can we get the signing URL as and when we update the placeholder with actual details and set. the status to SEND. In effect some thing like this.. Step 1: Prepare a package with a document, with one signer and 2 placeholders. Step 2: Create the package on the portal with STATUS = DRAFT. Step 3: Set the status to SENT. The user that has details will get the signing URL. After this set the package status back to DRAFT. Step 4: when the second user is available, we send the PUT with signer details and set the status again to SENT. Repeat #3 and #4 as required for all signers. Thanks again so much for your item and help.

OK. I confirmed that I can to set the status to "SENT" when there are placeholders ...

Hi Srini, When I was trying to send a package containing Placeholder Recipient, I received this API error:

{
    "code": 400,
    "messageKey": "error.validation.packageActivation.unassignedRole",
    "name": "Validation Error",
    "message": "There is a role with no signer."
}

It is somehow the same rejection when I tried to send package in web portal. However, your use case should still be doable, the only change I would suggest is in step1: Instead of using placeholder signers, you can create two signers with dummy names and emails, and until step 4, to update them with the real information. Duo

Thanks Duo. The approach we are thinking is that we will still treat it as a single signer, only we will download the last signed copy from OneSpan and have the next signer sign on top of that copy. So that mean for each signer we will create a new package.