DocuSign - Tag placement

Question

I have been using DocuSign's SOAP based API call "CreateandSendEnvelope" to create an envelope into specified DocuSign account. Everything seems to be working fine except I have been having difficult time while configuring tags for the recipient(s). I am using anchor tags as well as regular tags. Anchor tags are little easier to place as I can specify the tag unit.

I would like to know the following..

1) For the regular tags ( which are not anchor tags), what is the default unit? Can I specify the unit while configuring the regular tags?

2) While creating an envelope in DocuSign, when I add a new tag to the document, DocuSign immediately configures the tag position and puts the positions in the "From left" and "From top" fields.

I would like to know the unit of those positions. I have tried using those positions as X and Y offsets in regular as well as anchor tags but didn't work at all. If DocuSign can provide some sort of conversion from these units to Inches/Centmeters/Pixels, it will be so much easier for us to configure the tag positions.

3) I also have tried retrieving tag positions from the envelope that I have created using status update API calls but there also I found the same values.

Here is the snippet of my code that I use to add a tag..

    If Len(oldtab.AnchorTabString) > 0 Then
                'this is an anchor tag
                Dim tabitem As DocuSignServ.AnchorTab = New DocuSignServ.AnchorTab
                tabitem.AnchorTabString = oldtab.AnchorTabString
                If oldtab.AnchorTabUnit = "Inches" Then
                    tabitem.Unit = UnitTypeCode.Inches
                ElseIf oldtab.AnchorTabUnit = "Pixels" Then
                    tabitem.Unit = UnitTypeCode.Pixels
                ElseIf oldtab.AnchorTabUnit = "Centimeters" Then
                    tabitem.Unit = UnitTypeCode.Cms
                ElseIf oldtab.AnchorTabUnit = "Millimeters" Then
                    tabitem.Unit = UnitTypeCode.Mms
                End If

                tabitem.UnitSpecified = True
                tabitem.XOffset = CDbl(oldtab.XPosition)
                tabitem.YOffset = CDbl(oldtab.YPosition)

                tabitem.IgnoreIfNotPresent = oldtab.IgnoreIfNotPresent
                tab.AnchorTabItem = tabitem
            Else
                'this is a regular tag
                tab.PageNumber = oldtab.PageNumber                    
                tab.XPosition = oldtab.XPosition
                tab.YPosition = oldtab.YPosition                    
            End If

Please advise..

Minal

Answer 1

Answers to your questions:

1) The default unit for regular (i.e. non-anchor tags) is Pixels. For instance, if you set an xPosition = 100 and a yPosition = 50 then that means the tag will be placed 100 pixels to the right and 50 pixels down from the top left of the document. As the API documentation states, the default coordinate space has the origin at the top left of the document (each page).

2) Once again, the unit is Pixels. To test you can make the Get Tab Information for Recipient API call, which is my answer to #3. I just tested the call and it does indeed return the tab locations, which are in pixels:

3) This is the API call you can make:

GET https://{{server}}/restapi/{{apiVersion}}/accounts/{{accountId}}/envelopes/{{envelopeId}}/recipients/{{recipientId}}/tabs

X-DocuSign-Authentication: <DocuSignCredentials><Username>{name}</Username><Password>{password}</Password><IntegratorKey>{integrator_key}</IntegratorKey></DocuSignCredentials>
Accept: application/json
Content-Type: application/json`

Sample Response:

{
  "signHereTabs": [
    {
      "name": "Sign Here",
      "tabLabel": "Signature 1",
      "scaleValue": 1.0,
      "optional": "false",
      "documentId": "1",
      "recipientId": "152935b3-ace6-481f-be92-f2785e0bf28c",
      "pageNumber": "1",
      "xPosition": "474",
      "yPosition": "265",
      "tabId": "937521e5-7f3a-4a8a-9602-639c63a2b369"
    }
  ]
}

Answer 2

Thank you so much for your detailed answer.

In order to find out the tag placement on a document, here is what I have done..

1) I have created a draft envelope into my DocuSign account and have added a few tags - regular as well as anchor.

2) By clicking the properties of the tag, I got the location coordinates of the tag(s) in pixels.

3) I then have tried creating an envelope using an API call ( SOAP based API - CreateandSendEnvelope ) in which I have included the same document and have created the same tags as in the draft envelope. I have specified the X/Y coordinates of the tags with the values retrieved from the tag properties from the draft envelope.

4) I was not able to create an envelope and got an error .. "Tab is placed off of the page. Tab "signHere" is located off of page 1."

5) I also have tried retrieving the tab positions from the API call that you have specified and have tried using those values creating an envelope using an API call but got the same error. My goal is to first create an envelope in DocuSign and get the tag positions of all the tags so that I do not have to configure all the tags myself when I create an envelope using an API call.

Looks like, the tag positions that I retrieve are not the actual tag positions that can be used in creating envelopes using an API call!