9 Replies Latest reply on Aug 2, 2018 2:12 PM by eitanz88

    What are transient documents and where are they stored after posting to the RESTful API?

    envintusllc Level 1

      I'm trying to better understand what transient documents are used for and how they fit in to the EchoSign workflow. I've successfully written integration to upload a file via POST to the /transientDocuments and do receive the document ID, but I do not see the newly created document anywhere in my  EchoSign account. I do understand they only exist for 7 days and the returned document ID can be used in an agreement or widget, but where is this document viewable at in my EchoSign account?

        • 1. Re: What are transient documents and where are they stored after posting to the RESTful API?
          Jat ATS Adobe Employee

          Hi,

           

          Transient documents are the way to get your documents in an echosign Agreement. And as such are not to be avoided but are there to be used as a way to get your document to become available for use with other API methods. A transient document by itself has no meaning other than to be a source to be used in the Agreement, Widget or Library methods, hence the word transient. To make it the transient doc stick, you need use it in any of the aforementioned methods.

          There's no method to list, current, past or future transient documents, though you can create your own database of returned IDs and query that instead.

           

          An Echosign agreement is a package, consisting out of document(s), recipients and other agreement related info.  Using the REST api there is no mechanism allowing for a direct upload of a document in an Agreement package, like there is for example with the SOAP API. The soapAPI let's you upload content in base64 form directly into the Send Agreement method. rest requires you to create a transient document first, then to use this ID in Agreement, Widget or Library methods as the file source.

           

          Thanks

           

          Jat

          • 2. Re: What are transient documents and where are they stored after posting to the RESTful API?
            tylern68939392

            Can you post your code on how you successfully written integration to upload a file via POST to the /transientDocuments? I am struggling.

            • 4. Re: What are transient documents and where are they stored after posting to the RESTful API?
              EdRoxter Level 1

              It's pretty easy, you can simulate it with the REST API documentation:

               

              https://secure.eu1.echosign.com/public/docs/restapi/v5

               

              1. Open the "Base URIs">"Get Base URIs" accordion tab. If you have a legacy integration token, you can paste it into the "Access Token" field; otherwise click the "OAUTH ACCESS-TOKEN" button on the right hand side and tick, for example, "widget_write" if you want to create a widget based upon a transient document.

              2. If you have, either with integration token or OAuth access token, filled the "Access Token" field, click "Try it out" and the first API call is transmitted. It should return a JSON response with the API points that are to be used for further API calls. The demo page will use this data automatically for every other API call you make.

              3. Now open the "Transient Documents">"POST /transientDocuments" tab. Paste your access token from the baseURI call, select a file (PDF files will likely work fine). Click "Try it out".

              4. The transientDocuments call will return the transientDocumentID, which is valid for 7 days. It can only be used in further API calls, no other interaction with it is intended. It's just stored on the API server and assigned this ID.

              5. You may, for example, then create a widget based upon the file. Open the "Widgets">"POST /widgets" tab. Paste your Access Token. Then, enter a WidgetCreationRequest like this minimalistic one, for example:

              {  "widgetCreationInfo":{   "fileInfos":{    "transientDocumentId":"HERE_IS_YOUR_TRANSIENT_DOCUMENT_ID"   },   "name":"My Test Widget",   "signatureFlow":"SENDER_SIGNATURE_NOT_REQUIRED",   "counterSignerSetInfos":{    "counterSignerSetMemberInfos":{     "email":"countersigner@mydomain.com"    },    "counterSignerSetRole":"SIGNER"   },   "locale":"en_US"  } }

              6. Click "Try it out". It should work a few seconds, then return a success message with some of the widget's metadata like the public URL. At this point, the widget will, of course, be visible in the web interface as well.

               

              Voilà, this is how transient documents work. You just upload a file and can then reference its ID in further API calls. Of course, as soon as the agreement, widget whatsoever is created, it doesn't depend on the transient document anymore. So when the transient document gets deleted after 7 days, the widget (agreement...) created out of it will, of course, not vanish. The transient document is your raw PDF (doc, docx..) source file uploaded to the Adobe servers. As soon as you create something out of it with another API call, it will be converted into the "package" mentioned by Jat ATS.

               

              It's just a convenient way to transmit your base document to the API servers.

               

              Hope this helps with further understanding!

              • 5. Re: What are transient documents and where are they stored after posting to the RESTful API?
                briane50906161 Level 1

                Can someone please post code for sending a transient document in c#  I can't get it to work.

                • 6. Re: What are transient documents and where are they stored after posting to the RESTful API?
                  briane50906161 Level 1

                  Here's c# code that actually worked for me:

                   

                  if (!File.Exists(@"documents\1-Registration Form.pdf"))

                          {

                              return;

                          }

                          var objClient = new RestClient(@"https://api.na1.echosign.com:443/api/rest/v5/");

                          var objRequest = new RestRequest(@"transientDocuments", Method.POST);

                          objRequest.AddFile("File",  @"documents\1-Registration Form.pdf"), "1-Registration Form.pdf");

                          objRequest.AddHeader("Access-Token", "--My Token--");

                          objRequest.RequestFormat = DataFormat.Json;

                          IRestResponse objResponse = objClient.Execute(objRequest);

                          var content = objResponse.Content;

                          JObject jsonLinq = JObject.Parse(content);

                  • 7. Re: What are transient documents and where are they stored after posting to the RESTful API?
                    cliffwoodger

                    Hi Briane50906161,

                     

                    I wonder if you can help me.  I am trying to write a method in C# to upload a document to Adobe Sign and retrieve a Transient Document ID by return.

                     

                    Your code has helped me a great deal.  However, I am struggling with one thing.

                     

                    Whereas you are using a url (https://api.na1.echosign.com:443/api/rest/v5/ ), my understanding is that I should be calling the Base_Uris method (at "https://api.na1.echosign.com:443/api/rest/v5/base_uris" with my integration-key.

                     

                    I am doing this and it is working.  I am receiving an object which contains two items:

                     

                    api_access_point

                    web_access_point

                     

                    each populated with the url that I should be subsequently be using for the other method-calls (such as transientDocuments).

                     

                    The urls I am receiving for each, respectively, are:

                     

                    https://api.eu1.echosign.com/ and

                    https://secure.eu1.echosign.com/

                     

                    Just like you, I am passing in the access-point to my RestClient constructor, e.g....

                    var restClient = new RestClient(apiAccessPoint);

                     

                    and I am passing in "transientDocuments" on my RestRequest constructor...

                    var restRequest = new RestRequest(@"transientDocuments", Method.POST);

                     

                    I really need to use the web_access_point rather than the api_access_point but whether I try the web or the api, the response I am getting is:

                    "Not Found".

                     

                    I believe this is because the web-method I am trying to call, or the web-service itself, is not found.

                     

                    So, given the access-points I am receiving in response to the Base_Uris call, what should my full URI look like?

                     

                    I have tried just using the url "as is".  I have also tried appending ":443/api/rest/v5/" plus a number of other combinations but none of them seem to work.

                     

                    I would really appreciate your assistance as I have been struggling with this for days and you have a working method.  Perhaps you could simply modify your method to use the Base_Uris method and let me know what you did to make your modified method work?

                     

                    Thanks a lot for any assistance you can provide.

                     

                    Kind regards,

                     

                    Cliff

                    • 8. Re: What are transient documents and where are they stored after posting to the RESTful API?
                      davea42063757

                      Has anyone done this using cURL in PHP?

                       

                      I haven't been able to get this to work in PHP either

                      • 9. Re: What are transient documents and where are they stored after posting to the RESTful API?
                        eitanz88

                        I am working with PHP and I am having problems too.

                         

                        I am trying to upload a document and I am getting this error:

                         

                        Metadata

                        x-request-id : 821a370f-61e5-45fe-ab34-feb5f7db8d48

                        content-type : application/json

                        status : 400

                         

                        Body

                        {

                          "code": "BAD_REQUEST",

                          "message": "The request provided is invalid"

                        }

                         

                         

                        do you know what is the reason for this error?

                         

                        thanks