Is there a way to obtain the view document URL sent to the recipient?
I can enumerate the envelope status pulling back a multitude of URIs.
None which seem to match the URL and parameters.
If by document URL you mean the signing URL (ie. the URL token a recipient can use to sign an envelope) then no I don't believe this is possible.
URL tokens have lots of security built into them - when you generate a token it's only valid for 5 minutes and it is a one-time use, meaning if that URL is used or expired then you need to generate a new URL for that given recipient.
To help keep them even more secure if one is generated the actual link will not be saved and or returned anywhere to help prevent an attacker getting hold of it and using it before the true/intended recipient.
So as mentioned, once generated and sent there is no way to query the DocuSign system and ask for that actual URL that you've previously created. If you want to remember each URL you generate you'll have to do that through your app logic - but take note that they will only be valid for 5 mins and a one-time usage.
Related
The URL returned by the embedded signing url API method EnvelopeViews:createRecipient only lasts 5 minutes.
How can I get an embedded signing URL that will last longer?
The embedded signing URL time to live is only 5 minutes.
So the answer is to give your signers a customized url to your application. Then, when your signer clicks it, your application first obtains an embedded signing URL from DocuSign and then responds to the signer with a redirect to the URL.
Creating the customized URL
Create a database table in your application with columns:
ID
url_lookup_guid
account_id
envelope_id
signer_email
signer_name
signer_clientUserId
envelope_expiration_date (optional, see below)
When you want to create a unique URL for an embedded signer:
generate a guid. It will be used as the url_lookup_guid value
Create a record in the database table.
The url will be something like myapp.mycompany.com/sign/[url_lookup_guid value]
Creating the embedded signing ceremony
The user opens (GET call) the url you gave them. Eg myapp.mycompany.com/sign/1234567-1234-1234-123456789
Pull out the guid valid from the URL
Look up the record in your database
Use the other values in the record to make a call to EnvelopeViews:createRecipient
Receive the embedded signing URL response to the API call
Redirect the signer to the URL
Remove the database record or mark it as used.
Clearing old database entries
As noted above, you can delete database rows once they're used.
To clear out entries that were never used, a batch process can check the database each day for obsolete entries where the envelope has expired.
Either record the expiration date, or auto-create an insertion date
in the database. Then, once your account's default expiration time has been exceeded, make an API call to DocuSign to check that the envelope has indeed expired. (Its expiration date may have been extended.)
Notes
The URLs that you create can last as long as you wish, or until the envelope expires within DocuSign, whichever comes sooner.
The URL will enable the person to sign the envelope, so you'd probably want to include additional signer authentication from DocuSign to ensure that the signer is who they say they are.
Don't use the database's ID as the lookup key since you want to ensure that someone can't guess the ID of a record. Use a random guid as the look up key.
Your app will need an access token to make the API call to DocuSign. Since this is an autonomous task, use the OAuth JWT grant flow.
Don't create a new access token per invocation, cache the current access token.
Since it can take a couple of seconds to create the redirect URL (or more time if you need to obtain a new access token too), you might want to first return an intermediate page that shows a please stand by message and makes an Ajax call to your app to obtain the URL for the redirect.
I am using the DocuSign REST Api and noticed that the lifetime of a URL obtained using the EnvelopeViews API (https://developers.docusign.com/esign-rest-api/reference/Envelopes/EnvelopeViews/createRecipient) is only a few minutes. However, I have gotten emails in the past with DocuSign links. How are these links able to be added to an email (and therefore have a longer lifetime)?
Is there a separate API that can be used to get a longer-life link like the one in the email?
For example, here is an email that has a Review Document DocuSign link:
Good question. Here's what you can do.
Your application wants to let Larry sign a document using the
EnvelopeViews::createRecipient API call.
Your application should store the details needed for the API call in your app's database. Something like: envelopeId, signerEmail, clientUserId.
Create a guid for the database record and add it to the database record.
Now you can look up the database record via either the row's key or
via the guid. Ensure that the guid database column is indexed.
Now create a signing url that you will send to Larry. Something like:
https://myapplication.example.com/docusign-ceremony/[guid]
Send the url to Larry
When Larry clicks on the URL:
Your app is invoked
Look up the guid in the url in your database. You should find the
record that you stored there.
Retrieve all of the record's info: envelopeId, signerEmail,
clientUserId.
Call the EnvelopeViews::createRecipient API call with the data
and get back the signing ceremony url (that must be used within
5 minutes)
Redirect the user's browser to the url.
They'll sign the document(s) and then be re-directed back to your
application.
Done.
And guess what? This is pretty much what DocuSign does itself.
The response from Larry K above is correct, you would need to handle this on your side.
These are all the parameters that you can send as part of the request body for the POST {vx}/accounts/{accountid}/envelopes/{envelopeid}/views/recipient API endpoint and there are no options to set the expiration time for the recipient view that you create.
You could look into using PowerForms to see if they fit your needs. With PowerForms you can create a URL that users can click and it will allow them to fill out a specific DocuSign envelope. This might not fit your needs if you need to pre-fill some of the fields with information related to the specific recipient but it might be worth looking at.
PowerForms Documentation:
https://www.docusign.com/features-and-benefits/features/powerforms
Please correct me if I'm wrong but I think that your goal is creating the recipient view URL, creating an email formatted in a specific way and sending that email to the recipients.
If you use the branding feature you could specify the format for your email (if you want to use a specific message) and just send the envelope to your recipients. Once the recipients receive the email they'll see the message in the format that you specified and the link for accessing the envelope would be a regular DocuSign link that doesn't expire.
The link below shows how to create Brands in your account. Specifically signing brands would allow you to set the email content.
If you have multiple email formats you could create multiple brands and just specify the brandId when creating the envelope.
I hope this helps.
Branding:
https://support.docusign.com/guides/ndse-admin-guide-configure-branding
I'm using a service account to send an envelope on behalf of another user. Using the API, I'm then creating an envelope in the "created" status for manual tab placement. Once I get the EnvelopeSummary back from the DocuSign API, I'd like to create a URL that I will send send back to the "send on behalf of" user so he/she can easily begin to place tabs.
I've looked into using the CreateSenderView/CreateConsoleView methods, however I don't know the AccountId/Password of the "send on behalf of" user nor do I want to use their information. Instead, I'd like to redirect the user to DocuSign where they can login and then after login, be redirected to the envelope.
I've also looked into creating my own URL from the envelopeId:
string envelopeId = "1ddff790-ad2d-4fb6-87c2-4b5e449898c9";
string redirectUrl = "https://appdemo.docusign.com/prepare/" + envelopeId;
This appears to redirect the user to the envelope if they are logged in, and if not, they will be prompted to login and then redirected. This is the functionality I am looking for, however, I'd like to use the API to generate this URL if possible since I'm not sure whether the referenced URL will remain static over time.
Any ideas?
If you haven't already done so, I'd suggest that you review DocuSign API documentation for the Send on Behalf Of (SOBO) feature. As the documentation describes:
The SOBO feature can only be used when both users are members of the same DocuSign account.
You (your application / UI) must collect username and password at least one time from the user whom you're sending on behalf of -- because you need their username and password in order to obtain an access token that can subsequently be used to submit API requests on their behalf. Since tokens do not expire (and are valid even if/when the SOBO user changes their password), you only need to collect username/password one time from the SOBO user, then use those credentials to generate an access token which can be used indefinitely to send on their behalf.
I would not recommend using the envelopeId to create your own URL, as this functionality is not supported by DocuSign -- even if it works today, there's no guarantee it'll continue to work in the days ahead.
Finally, issuing a Create Sender View request (using SOBO) will return a URL that can be used to launch the sender (tagging) view for the specified Envelope. Do note, however, that the URL will expire after a short period of time (5 minutes?) -- which means that you should not issue the Create Sender View request to retrieve the URL until the user (sender) is ready to tag/send the Envelope. For example, issuing the request to generate the URL and then emailing that URL to the sender would not be feasible -- since there's no guarantee that the user (sender) would open the email and click the link to launch the sender view before the link expires. Instead, you should provide the sender with a way to indicate to your application when they are ready to tag/send the Envelope, and then issue the Create Sender View request at that time and redirect the user (sender) to that URL immediately upon receiving the URL.
Update (Legacy SOBO)
#EnterTheCode -- thank you for the clarification that you provided in the comments. Your understanding of Legacy SOBO functionality is correct; that is, it does not require that you obtain an access token for the SOBO and it does not require that you obtain the SOBO user's password. You can simply include the X-DocuSign-Authentication request header to specify the username and password of your "service account", the integrator key, and the email address (or user ID) of the user whom you're issuing the API request on behalf of.
(Side Note: Although Legacy SOBO is apparently still supported, it's no longer recommended for service integrations. Instead, DocuSign now recommends this approach.)
Putting SOBO authentication technique aside though, the rest of my original answer still applies to your scenario. That is, to retrieve a URL that can be used to launch the sender (tagging) view for the specified Envelope, you'll need to use the Create Sender View operation. And, as mentioned previously, the URL that's returned by that operation will expire after a short amount of time -- so be sure to account for that in how you design your implementation.
Why you want to use SOBO, if you want someone to update the envelopes then you can add that user as first recipient in the envelope with recipienttype as "Allow To Edit" ("editors" in API term). With recipient type as "Allow to Edit", DocuSign will send an email to the recipient and then recipient has to login into his DocuSign account, after that user will be able to access the envelope and can do the editing of the envelope like doing tagging of document with DS Tabs, adding, removing recipients etc, in same way as "Sender View". In this way you don't need to create a webpage for embedded sending view.
I'm using DocuSign's REST API to create envelopes in embedded signing mode. With the function CreateRecipientView i get only a temporary link. But i would prefer to get an permanent link like in the notification mail. How can i get this link/URL?
Getting permanent signing links is not possible using the DocuSign rest API.
For remote signers, only the signer can receive the signing link through email. No one else will have access to the signing URL.
Setting permanent signing/access link is possible with "embeddedRecipientStartURL" by using a captive recipient aka "clientUserId" and your own URL endpoint whereby you authenticate your users and determine if they can access the envelope via a Request Recipient View.
Documentation here.
You can also request emails be sent per captive recipients as well as many other "Portal" centric options that put you in full control of the user experience.
To give your signers permanent links, your application creates the links by itself. Eg myapp.myserver.com/signing_links/95a086f7-a76e-40ec-938e-987be996d220
The number should be a guid, not a database record key. This is needed to prevent someone from guessing what one of these permanent links is, so they can't read (or sign!) someone else's documents.
When someone opens their browser to go to one of the signer links, your application looks up the guid in the your app's database. The database record will include the DocuSign envelope_id and the recipient_id that the link represents.
Next your app uses that data to request an embedded recipient view link from DocuSign. Then (if you get a good response back from DocuSign), your app redirects the user's browser to the signing page on DocuSign.
(You'd get back an error from DocuSign if the recipient had already signed, or the envelope had been voided, etc.)
Guess what? The above is more or less how DocuSign gives out the "permanent" links in its emails--those links always redirect to one of the 5-minutes-only signing ceremony links.
Remember that you need to authenticate the signers, or include additional authentication options in your envelope, since you don't know who is going to end up pressing one of your app's signer links.
Setting vs Getting permanent signing/access link is possible with "embeddedRecipientStartURL" by using a captive recipient aka "clientUserId" and your own URL endpoint whereby you authenticate your users and determine if they can access the envelope via a Request Recipient View.
https://www.docusign.com/p/RESTAPIGuide/RESTAPIGuide.htm#REST%20API%20References/Recipients/Signers%20Recipient.htm
You can also request emails be sent per captive recipients as well as many other "Portal" centric options that put you in full control of the user experience.
So Net/Net, LarryK and CodingDawg are correct, each from a specific view. It ultimately is up to you to decide which way works best for your application and users.
I have implemented DocuSign's Embedded signing flow with our application. Our use case : customer of our app sends email with link to the client that has to sign a document. That is our app link. On clicking on email we are opening DocuSign (in IFrame of our app) and open url as following :
https://demo.docusign.net/Signing/startinsession.aspx?t=776a1a9c-72c6-4c62-9243-2807db18f78a
If user clicks on link and finish signing/declining everything goes OK. Elsewhere user opens a link, do nothing and re-open a link immediately DocuSign sends ttl_expired status. Same response I get if user clicks on link after some time - let say 1hour.
As I found online, for this flow :
Recipient Tokens expire five minutes after they are issued by DocuSign. If a Recipient Token URL is invoked after it is expired, the user is re-directed to the Callback URL specified in the RequestRecipientToken request with event code TTLExpired.
Recipient Tokens expire upon being successfully invoked.
Active Recipient Tokens expire if the envelope is voided.
Developer Guide 85
Five minutes is the default "Time to Live" for Recipient tokens. This is a configurable setting.
Source
If it is like that, which DocuSign flow can meet our use case, or I have to change something in existing flow ?
You do not need to create a new envelope each time you encounter this error. In fact, that's a bad decision as that will start to eat up at your monthly envelope limits that are allowed on your DocuSign account plan.
Instead, if you generate a signing URL and the recipient opens it but does not sign and closes out and eventually needs to get back in and sign that envelope, you can simply generate a new recipient view (signing URL).
With the newly generated URL the same rules apply... if they don't use it within 5 minutes or they open but don't sign the once again you'll need to create a new URL token, but that's much better than wasting a whole new envelope. That simply counts as one extra API call, which you are allowed 1,000 per hour per account.
The retrieved URL is one-time use and expires after 5 minutes. Once Docusign detects that you have loaded a retrieved URL, it will no longer work. As stated in a previous answer, if you haven't loaded it within 5 minutes, it will also no longer work. The ttl_expired code will appear in both cases.
You just have to request the signing URL again if its used or expired. Do not recreate the envelope.