I can successfully add various tabs to a recipient of an draft envelope via the REST API. However, when I go to look at the target document via the manage tab of the website and I check the settings on the tab, the location values are completely different than what I entered via the REST API.
What is the difference? Why the difference? What exactly is the unit of measurement on the webpage as well as the API?
If you're merely trying to determine the X/Y coordinate values to use in the REST API Create Envelope request such that tabs are displayed in expected/desired locations when the Envelope is viewed in DocuSign, you might try the following:
1) Using the DocuSign web console, create a (Draft) envelope and upload the document(s) that you will be sending via the API. Also use the web interface to drag/drop tags into the proper locations on the document(s). (Save as a Draft Envelope.) For example, here's a document where I've added two tags (SignHere and DateSigned):
2) Next, inspect the tab properties (X/Y coordinates) for that Draft Envelope via REST API request: (https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/{{envelopeId}}/recipients?include_tabs=true&include_extended=true). Here's an example response -- the highlighted values show X/Y coordinates for the tabs, according to the REST API:
3) Finally, to create an Envelope with tabs placed at the expected/desired locations when the Envelope is viewed in DocuSign, use a REST API "Create Envelope" request that contains the same documents used in Step #1 and specifies the X/Y coordinates that you received in Step #2 response (i.e., the X/Y coordinates according to the REST API). For example, here's the "recipients" portion of the Create Envelope (JSON) request -- using X/Y coordinates that I received in Step #2 response.
"recipients": {
"signers" : [{
"email": "bobsemail@outlook.com",
"name": "Bob Adamson",
"recipientId": "1",
"routingOrder": "1",
"tabs": {
"signHereTabs": [
{
"recipientId": "1",
"tabLabel": "Customer_Signature",
"documentId": "1",
"pageNumber": "1",
"xPosition": "99",
"yPosition": "424"
}],
"dateSignedTabs": [
{
"recipientId": "1",
"tabLabel": "Customer_Date",
"documentId": "1",
"pageNumber": "1",
"xPosition": "373",
"yPosition": "456"
}]
}
}]
}
If I then view (in DocuSign) the Envelope created by my "Create Envelope" request described in Step 3, I see that the tabs are placed exactly where I expect/desire them to be:
Obviously the process I've describe here is not ideal (it'd be much better if the X/Y coordinates set/retrieved via API matched Tab properties shown in the console), but perhaps it'll get you the end result you're shooting for.
(Supplying this as an "Answer" instead of a "Comment" so that I can include code and images. I realize this doesn't necessarily answer your question -- but hopefully someone from DocuSign can comment on the scenarios I've outlined to provide clarification.)
Interesting. Even if (for whatever reason) the unit of measurement for the X-Y coordinates that you supply via the API is different than the unit of measurement that the DocuSign web console uses for tab "Location" properties -- I'd expect the multiplying factor to be the same. However, this does not appear to be the case.
For example -- if I submit an API request to create a Draft Envelope with a Signature tab that specifies xPosition=100 and yPosition=100 (as shown in the partial request JSON here):
"recipients": {
"signers" : [{
"email": "bobsEmail@outlook.com",
"name": "Bob Adamson",
"recipientId": "1",
"routingOrder": "1",
"tabs": {
"signHereTabs": [
{
"recipientId": "1",
"tabLabel": "Customer_Signature",
"name": "KB_TEST_SIG",
"documentId": "1",
"pageNumber": "1",
"xPosition": "100",
"yPosition": "100"
}]
}
}]
and then open that Draft Envelope using the DocuSign web console and inspect the "Location" properties of the Signature tab, I get this:
Notice that even though the API request specified the same exact value (100) for both xPosition (definition: "indicates the horizontal offset of the tab on the page, in a coordinate space that has left top corner of the document as origin") and yPosition (definition: "indicates the vertical offset of the tab on the page, in a coordinate space that has left top corner of the document as origin"), the values that are shown in the console for From left and From top no longer match each other:
As another test, I tried doing things in reverse:
The API response shows xPosition=48 and yPosition=27 (even though I set From left=100 and From top=100 when creating the draft envelope via the console).
The only logical conclusion that one can draw from all this is that the xPosition and yPosition coordinates specified via the API don't seem to map in any direct (and consistent) way to the From left and From top coordinates shown in Tag Properties within the console. Hopefully someone from DocuSign can confirm and/or clarify this behavior.
What's even more bizarre is that a Tag's X-Y coordinates returned via the SOAP API don't match the X-Y coordinates returned via the REST API (and of course, neither REST nor SOAP coordinates match what the console shows):