
Lessons from Failed DocuSign Integration - profsmallpine
https://profsmallpine.com/writing/lessons-from-failed-docusign-integration
======
inoda
I was on this project and can speak a bit more on the technical details here.

A couple of high level goals:

1\. We wanted to use their embedded flows, to keep the experience within our
application as much as possible.

2\. We wanted to avoid having to create a DS user for every user in our
application that turned on this feature. We were looking for using 1 “API
user” to make requests, handling data scoping ourselves within the
application.

The actual issue in more detail:

1\. Go to an embedded page, authenticated as the “API user” (which _looks_
like you’re sandboxed within DS to the embedded page)

2\. Refresh the page

3\. You now can click around the entire account - viewing any data that
belongs to the API user (in our case, all of the data).

At this point (as the OP called out), we realized we had no choice but to
create DS users. But we still wanted to hide this process from our users,
keeping DS as embedded as possible. The issue was their “regular” user
creation flow involves a email going out to the user to confirm - obviously
this is unideal if our goal was to wrap DS and hide it’s existence as much as
possible from users.

DocuSign offered a workaround for this, which involved basically getting
shifted to a legacy version of the API, with no hard promise of it _not_ being
sunsetted. By then, we had had such a poor experience with non-answers from
their team that we called it quits.

I hope this clarifies some of the technical problems we were trying to solve
for.

Edit - I'm sure DocuSign can solve for some use cases. Obviously, they have a
large user base and I'm sure most of them are at least satisfied, if not
happy. But if you're trying to wrap an e-sign provider within your
application, I would recommend HelloSign 1000x. HelloSign's API is a first
class citizen whereas DocuSign's felt more like an afterthought.

~~~
inoda
I'd like to add a little more to this - our main frustration isn't necessarily
because of these technical difficulties. Communicating implementation details
and 3rd party integrations can be challenging, especially if one side of the
convo is not super technical. That is totally understandable, and probably
inevitable.

The main reason this felt so...sucky for lack of a better term, is that we had
_multiple_ discussions about our use case and were told that this would be
supported (again, this turns out not to be true? not a huge deal, it happens),
and were asked to pay $20,000 upfront of which we got $0 back once realizing
the original promises were not true.

As OP pointed out, 20k for a huge company like DS might not seem like much,
but for a small start up like us it is. Just from a consumer perspective, this
seems like a crappy way to conduct business.

~~~
justinclift
Sounds like the - unfortunately very common - thing where sales people make
promises which aren't delivered on.

Seems to be the sales people doing this get bonuses regardless, even though
the customers get shafted, and their own tech staff generally get shafted too.
:(

------
horsawlarway
Maybe the goal here wasn't to be technical (although I'm not sure why given
it's an article about docusign api integration) but this is a WHOOOOOLE lot of
text with basically nothing worth reading.

>I was annoyed that they didn’t provide a secret key to authorize API requests

Yeah... they don't do that for a reason. They appear to support a fully
fledged OAuth implementation ([https://developers.docusign.com/esign-rest-
api/guides/](https://developers.docusign.com/esign-rest-api/guides/)). I
haven't used it, so maybe it's terrible, but I'm suspicious of the author at
this point.

>DocuSign API docs are very quirky

But no discussion of why, or what he would expect instead. This actually
sounds like the author is lost because they don't understand OAuth again (and
to be fair, I've implemented OAuth and it's easy to get wrong).

>Someone on the team noticed that if you refresh the page, you get logged in
as the user that was making the API request. [...] About a week later, we were
informed that this is intentional, and they were worried about breaking anyone
that is using this as a feature.

This honestly sounds like they were politely telling you that you haven't
implemented OAuth correctly. You should be making the request with the token
of the delegated user, not a generic account.

>I got this working, but it took some janky work to re-work the JWT flow to
manage hourly expiring tokens for all of our user that choose to enable the
esignature feature.

This is what refresh tokens are for. I highly doubt the refresh token expired
in an hour, but hey - I haven't used it so maybe I'm wrong.

\---

I honestly believe I can summarize this whole article as: Dev takes first
steps into OAuth and gets lost...

~~~
fyjvd90
OAuth is going to be hard to use if you don’t create an account though,
there’s no way for DS to know what scopes to restrict the user to, it sounds
like that was the core issue that broke their workflow.

~~~
sunir
I think it is very unclear what is real and not real. OP is mostly passing
blame to DocuSign without achieving full understanding themselves. That is
more an indictment on OP than DocuSign even if there is some actual session
security problem with DocuSign (likely from the deprecated API).

~~~
stingraycharles
Yeah and it sounds like they were trying to do something that makes no sense
for DocuSign to support: use a single account to sign all users’ documents.

DocuSign has a legal obligation here to prove authenticity, how are they ever
going to be able to do that if everything is behind a single account?

They support oauth and that makes sense and should be the way to do it.

~~~
treis
>DocuSign has a legal obligation here to prove authenticity, how are they ever
going to be able to do that if everything is behind a single account?

By the signature.

I don't know how it works in DocuSign's internals, but there's no requirement
for the signer to have an account. The point of the account is for users to
see all of their documents in one place. In OP's case that's everyone's
documents because they use a single account.

[https://support.docusign.com/articles/How-do-I-sign-a-
DocuSi...](https://support.docusign.com/articles/How-do-I-sign-a-DocuSign-
document-Basic-Signing)

~~~
lowercased
Yep. I just signed things via docusign 2 weeks ago. There was no 'create an
account' first. IIRC, there was something at the end indicating I could create
an account _after_ the doc was signed, but I got a copy via email anyway which
was all I needed. The last thing I need is _yet another_ account/login for
what is essentially a one-time thing.

------
kodon
I had a project that used docuSign a few years ago. There were some very
strange things going on with their API.

I remember having to call them asking where to find a template ID so I could
save that and send out the proper doc to customers. It was not listed anywhere
on the developer dashboard. The rep told me in a very condescending way that
it template ID was part of the URL. I should have known to just use that!

My app was written in a python backend. They had a some API examples in
different languages for their docs. The python example was a total
embarrassment. It was clear that the person who wrote it had no experience
with python at all. I am not trying to be mean, it was that bad. Every line
ended with a semicolon (in python this is not an error, but is officially
discouraged). The person also seemed to not be aware of a dictionary. They
built their json paylod by concatenating text. It was the messiest python code
I had ever seen. I think this particular bit of code is gone now, but it was
incredible.

I felt so bad that I emailed them some suggested fixes and asked if they had
python experience. They responded with a something along the lines of ya, we
had the java guy do that. But the code stayed up there for a long time...

~~~
PostOnce
I also worked on a Python project that integrated DocuSign.

I was able to hack together solutions and skirt around DocuSign's many
problems, garbage documentation, and general very-low-quality API, but in no
circumstance would I ever recommend it to anyone. Late in the project I
seriously considered throwing it away and switching to another API.

The other API I considered was:
[https://app.hellosign.com/api/pricing](https://app.hellosign.com/api/pricing)

This is literally ten times the price of DocuSign and I don't know how long
they'll be in business, so it's a hard sell to buy into that. The API docs
looked way way better (like stripe or twilio or slack apis, rather than some
janky enterprise nonsense), but development and hacking around DocuSign was a
one time expense, and the API is an ongoing cost.

If remotely possible, I'd just sign stuff in person and mail or fax it, since
all this stuff just adds difficulty, complexity, and cost, to very little
benefit unless you have a LOT of people signing stuff. The application I
worked one was for one or two signatures a month, so not worth the trouble.

------
ecshafer
I've done a docusign implementation, and I don't really agree with them. Their
API is fine honestly, I think their documentation could be better and some
things are named awkwardly. But the implementation really isn't hard, my only
real complaint is that when we did it they pushes the DocuSign connect service
really hard, which honestly was kind of a waste and didn't live up to many of
their promises, but that's normal b2b upselling. It's a normal API, and
definitely not as bad as this person makes it seem.

~~~
Bamafan
Whether an API is "good" or "bad" often is dependent on the requirements of
the calling client. At the beginning of projects when client requirements are
unclear, it is often hard to determine whether a supporting API/library truly
meets your needs.

~~~
ecshafer
That is true. To move away from language like good or bad. I would say
DocuSign is quite reliable, we had one outage that was their fault and we were
an edge case. I would also say that their API is sufficient for 95% of use
cases or more with very little work arounds. Their customer success architects
or whatever they call them were also pleasant to work with and responded
promptly.

------
larrykluger
I am DocuSign’s Lead Developer Evangelist. Thanks to Joseph (OP) for writing
this up and to everyone who has contributed to this thread including both the
positive and negative comments about integrating with DocuSign.

The problem OP ran into is really one of documentation and not a bug or
security issue.

I agree that our docs for the embedded sender view should clearly state that
the method’s URL gives full access to the sender’s account, and we’ll fix that
ASAP. As others have commented, the assumption of this API method is that each
sender has their own account. I also agree that the OP’s use case, which
requires that the sender view’s capabilities be strictly limited to the
current envelope, is valid. It is under consideration for our roadmap.

A workaround: I recommend that API applications complete the sending process
programmatically including document tagging, etc. This also provides the best
user experience for the sender.

We actively monitor and reply to the “docusignapi” tag on StackOverflow (I’m
“Larry K”), if you want to reach out to us there.

~~~
jessaustin
_I also agree that the OP’s use case, which requires that the sender view’s
capabilities be strictly limited to the current envelope, is valid. It is
under consideration for our roadmap._

If this case is valid, other customers besides OP are doing the same thing.
They probably have the same vulnerability. It's also not clear how document
tagging can stop this hole. If there is just one user then that user's users
can't have that user's creds. Rather they must be limited to specific tokens
that give them access to their specific documents.

------
uniformlyrandom
Looking at the API description (very detailed BTW)
[https://developers.docusign.com/esign-rest-
api/guides/authen...](https://developers.docusign.com/esign-rest-
api/guides/authentication/oauth2-jsonwebtoken) , it does look like they used a
wrong flow for the use-case, and then invented some shortcuts to make it work
(which understandably did not work out well).

It does look like onboarding failure, but there is so much you can do to steer
the customers towards the right path. I am not completely convinced that this
was Docusign's fault.

------
propter_hoc
FWIW, I've developed a lot of this sort of tool. For some reason, Adobe E-sign
services (formerly known as EchoSign) rarely comes up, but it's actually quite
good and cost-effective to develop with.

Docusign is indeed pretty terrible as an API, but it does have the benefit
that users have heard of it so it has a certain institutional credibility -
which is usually important if you're developing the sort of app that needs an
e-signature process. On that front, all of our clients were very comfortable
with Adobe as a secure service provider - it was something we publicized, in
fact.

I've played a bit with Hellosign. While I've heard they have a nice API, they
don't have the institutional credibility that Docusign and EchoSign have.
Also, their pricing was way, way higher than EchoSign's, in my experience. I'd
love to learn more about them, though.

~~~
btown
Can you give any guidance on Adobe/EchoSign's API pricing? Seems like it's
behind a "contact us" enterprise plan these days?
[https://acrobat.adobe.com/us/en/sign/pricing/plans.html](https://acrobat.adobe.com/us/en/sign/pricing/plans.html)

It generally seems ridiculous to me that it's 2019 and APIs like
[https://app.hellosign.com/api/pricing](https://app.hellosign.com/api/pricing)
are priced per signature _request_. Even if each finalized signature comes
with regulatory retention requirements, that's far from a linear cost... and
these are PDFs we're talking about retaining, not videos. The whole ecosystem
reeks of price fixing.

~~~
propter_hoc
Yeah, there's little I hate more than opaque "contact us" pricing. To my
surprise when I inquired EchoSign was actually much cheaper than the
alternatives. At the time, I had an API license from EchoSign that cost a few
hundred dollars a year for a very large number of monthly document signings,
with no hard limit (but polite requests to buy additional licenses if you went
above the limit). I don't know if they've kept this pricing model though.

------
jrm2k6
Advice: Skip straight to the situation paragraph as anything before that isn't
about the DocuSign integration, not sure what the first section brings to the
whole article.

~~~
jessaustin
This is the third entry in the blog. Author just had some stuff to get off his
chest. He might want to split this into two entries...

------
nowarninglabel
The author seems to have buried the lead here: "Someone on the team noticed
that if you refresh the page, you get logged in as the user that was making
the API request"

And that is how the implementation works for many of Docusign's customers as a
'feature'. If that's true, that would seem like a potentially exploitable
security hole. However, I'd have to question if that had something to do with
the particular implementation, otherwise I'd expect more focus on the security
repercussions.

~~~
EpicEng
From what I can tell, the issue is that the OP was using a single user to
perform all calls. They didn't want to sign users up individually, so they
took this workaround route and found out that it wouldn't work after all.
TLDR; they weren't using the API as intended because they wanted the DS part
of the UX to be transparent to the user.

------
nsedlet
We just completed an embedded signature integration with HelloSign. The
HelloSign API plans were expensive - but still a fraction of what DocuSign
charged (at the time HS was 20% as expensive - pricing seems to have gotten
more comparable now).

Integration was easy. The Ruby SDK & JS lib worked great (we have Rails back-
end / React front-end). Customer service has been good & responsive. They have
to approve your UI before giving live access - but once we had the integration
working it took < 1 day to schedule the meeting, do the screenshare, and get
approved.

Two slightly annoying things: (1) they don't have per-request fees if you go
over your allotted usage. You'll get automatically bumped to the next plan
which gives you 3x the request and is almost twice as expensive. (2) they
wouldn't let us go month-to-month since we had an existing annual plan that we
wanted to be under the same account (so we can share templates). This is tough
since it's difficult for us to predict how many requests we'll need.

------
jelling
Just use HelloSign. Their developer support is the best I've had from an API
company - you email them and you get support from an actual developer - and
they smartly do things to save everyone trouble like creating an API debug
console so you can see what they receive on their end. I wish all of our API
partners followed their lead.

The best thing I can say about Docusign is that it is way, way better than
Adobe Sign's absolute garbage support. The Adobe software may work but if you
have the slightest problem with the API you will be in support hell.

------
bdauvergne
All those online signatures "click to sign" services are useless anyway, they
have absolutely no legal value anywhere (their EIDAS/ETSI whatever are just
buzzwords), even in France from where docusign is coming.

[https://www.cryptomathic.com/news-events/blog/us-court-
rejec...](https://www.cryptomathic.com/news-events/blog/us-court-rejects-
docusign-e-signatures-as-method-to-provide-digital-authorization)

~~~
kevindong
That article is pretty clear that the docusigned documents were invalid due to
that specific court's rules.

To quote from the ruling [0] directly:

> Although DocuSign affixations and other software-generated electronic
> signatures may have a place in certain commercial and other transactions,
> they do not have a place as substitutes for wet signatures on a bankruptcy
> petition, schedules, statements, and other documents filed with the court,
> and they do not comply with this court’s local rule.

[0] (see page 7) :
[http://www.caeb.uscourts.gov/documents/Judges/Opinions/Local...](http://www.caeb.uscourts.gov/documents/Judges/Opinions/Local/Mayfield-
ForWebsite.pdf?dt=202716160)

~~~
DaiPlusPlus
A real solution is a proper PKI - a great way forward would be if the US
federal government issued citizens with X.509 digital certificates when they
get their passport renewed: they’ve done the task of verifying identity, they
just need to co-sign a cert and give people $5 smart cards with their $100
passports.

With state-sponsored PKI we can eliminate so many headaches and rockblocks in
the digital economy and paperless government.

~~~
anitil
Given the whole SSN debacle and the low passport ownership in the US, I see
this as functionally impossible.

------
jabart
We tried something similar years ago with DocuSign, and needed the ability to
sign in person with two different people, one acting as a witness, with a
potential third person being remote via email. It was not supported at all.
Built our own internal system to handle esignatures, worked great, never
looked back.

------
nartz
The article was a bit meandering (bit of a bildungsroman), but good to know to
avoid docusign apis. Might have been able to find out how much it sucked just
by googling more "docusign alternatives" or "docusign api sucks" =D

------
jordache
When we tried to bring docusign on board back in 2015-2016, it didn't feel
like a very robust product in terms of user accounts management.

They had a legacy instance and a v2 instance (w/ new UI). Enterprise
integration was against the legacy instance. Accounts created in one instance
does not carry over to the new instance. User who self registered in new
instance some how makes authentication into the legacy instance very
difficult.

As a user with admin access to docusign, there were a paltry of user
management features. I had to delete individual users. No way to filter or
batch any user oriented actions.

------
ykevinator
We rolled our own bc out of box solutions were crazy expensive. Any one else
do this? I'm kind of surprised how much people are willing to pay for
something that is not that hard to build. You can't build your own twilio or
Google maps but Hou absolutely can build your own signature feature.

------
thaumaturgy
I've been working a lot on a project recently with a fair bit of Docusign
integration.

Some notes:

* Their API documentation really is garbage. If you're signed in to your developer account, you get access to marginally better documentation. This makes it hard to abuse Google to find things you're looking for. Specifically, the documentation is incomplete and difficult to navigate, largely because they appear to have relied on Swagger to generate the whole mess.

* Their support sucks, and exists mostly to try to get you to pay for their team to write code for you to interact with their code, rather than fixing their documentation.

* The API has some warts. I wouldn't care about the warts so much if the documentation compensated for it, but it doesn't, so I've burned lots and lots (and lots) of hours trying to figure out the weird bits. For example:

> You specify the difference between an "embedded" and "remote" recipient by
> setting a clientUserId attribute;

> But, if you specify both a clientUserId and a client name attribute, then
> the API call to createRecipientView will probably return a "User not found"
> error (see for example
> [https://stackoverflow.com/questions/20500630/unknown-
> envelop...](https://stackoverflow.com/questions/20500630/unknown-envelope-
> recipient-but-the-recipients-actually-do-match\);)

> You send an envelope not with an API call like sendEnvelope, but by setting
> the envelope status to "sent";

> Exceptions thrown during the authentication process by default set the
> Exception's error message to "Error connecting to the API...". Guess how
> much fun that was to debug?

* And their library for PHP is really a steaming pile. It's just a wrapper around curl, auto-generated by Swagger. It pretty much demands a wrapper around their library to be able to work with it effectively and compensate for all the warty bits.

I haven't quite got to the point of _hating_ Docusign, but I don't love them,
and wouldn't recommend them to other developers. I did find HelloSign early on
in this project, and their API documentation
([https://app.hellosign.com/api/documentation](https://app.hellosign.com/api/documentation))
is everything that I wish Docusign's was, and they clearly make a much greater
effort to be attractive to developers.

I'd love to link some of the Docusign support articles and such I've filed
under my "docusign_sucks" tag, but you need to be signed in to your Docusign
developer account to view them...

------
diminoten
> we’ve tried to build as much as we can as to skip dependencies, I’ve spent
> enough time in rails to appreciate debugging owned code - an argument for
> another time...

Okay, I'll bite. I have no experience in RoR, but does this line suggest that
RoR _encourages_ NIH?

This line feels like that scene in a horror movie, right at the beginning,
when the camera lingers a little too long on the janitor's face as he cracks a
smile that's wider than it should be.

Red flags:

* NIH (mentioned above)

* Using Go in production (more specifically, complaining about the lack of support for Go in production -- you should have known what you were getting into)

* Announcing a hacked-together MVP to the whole company

* Escalated to a VP for a technical issue

* Not using the company's recommended workflow, instead building your own

There's no way that the inability for the author to deploy DocuSign, an API
that hundreds of companies successfully use, is on DocuSign.

Also, an maybe this is just a cynical view, but when you start your cautionary
tale with a literal, "It all started when I was 11", it's kind of hard to
relate.

~~~
briandear
What is NIH?

~~~
tectec
Not Invented Here, a term normally used to describe the thinking that instead
of using libraries we should write all our own code.

