Welcome to Developing with DocuSign.
This episode covers the DocuSign API Explorer.
This developer tool lets you explore and execute
DocuSign REST API methods in an interactive environment.
I'm Matt Lusher of the DocuSign Developer Content Team.
We create content and tools to help you
develop DocuSign integrations.
In this video, I'm going to show you
how to find and use API Explorer to learn
how DocuSign REST API calls work.
API Explorer is accessible from any API method
page in the DocuSign developer center's API references.
Here I'm on the e-signature REST API reference page documenting
one of the most important API methods--
Envelopes: create.
You use this method to create and send envelopes
for electronic signature.
The pair of buttons at the top of each API reference page
lets you select whether to view the reference documentation
or the API Explorer.
I'll select API Explorer.
Notice the message at the top.
To use API Explorer you need to be
authenticated using your DocuSign developer account.
That's because this isn't a simulation.
You're about to execute a real API call
against a real DocuSign server.
DocuSign developer accounts operate in the DocuSign
developer environment.
Select the blue button, as I'm doing here,
to log in to your developer account, or the Create Account
link to create a new one.
Developer accounts are free and give you access
to nearly all DocuSign features.
I'm now prompted to log into my DocuSign developer account.
Behind the scenes, this executes an OAuth authentication code
grant flow resulting in an OAuth 2.0 access
token that API Explorer caches for the rest of the session
or until the token expires.
DocuSign access tokens expire after eight hours.
Now I'm ready to try out this API call
using the controls on the page.
Notice that from the start API Explorer
shows you the headers, parameters,
and JSON body of the call as well as the calling syntax.
The syntax and JSON body are dynamically
updated as you fill in parameters so you can see
how the call is constructed.
Now is a good opportunity to point out the Download button.
When you click Download, API Explorer
exports the API call in its current state to a JSON file
and downloads it to your machine.
You can then open that file to see the structure of the call.
You can do this at any time while you're
working on the API call with whatever parameters you've set
or changes you've made and you'll
get the results of your work reflected in the file.
This is a great way to see how the call works.
The Envelopes: create call has many parameters.
You can scroll through the list, but I'm
going to stick with just the basic parameters for this demo.
API Explorer labels required parameters for you.
The first and only required parameter is account ID.
This is the API account ID you listed
on your developer account settings
on the Apps and Keys page.
API Explorer reads your account ID
when you log in and automatically inserts it
for you.
You can see its value in the parameter field
as well as in the call syntax.
As I scroll down to the body section of API Explorer,
you'll notice the Form Editor and JSON Editor buttons.
These two buttons toggle the display of the body.
By default you see the form and you
can enter whatever values you want that way.
Select the JSON Editor, however, and you'll
see an open text editor.
I'll show you more about that soon.
The body of the Envelopes: create
call consists of the envelopeDefinition.
envelopeDefinition is an object that
contains all the information needed
to specify the DocuSign envelope you want to create--
the documents to attach, the email subject
line if you're using email, the envelope recipients, tabs,
templates, and more.
Notice that the envelopeDefinition object
isn't actually required.
You can execute the envelope's create call with nothing
more than your account ID.
Doing that wouldn't accomplish much, however,
so I'm going to add some details to the envelopeDefinition
object to make this demo practical.
For this demo, I'm going to add a single document
to send for e-signature.
To do so, I scroll down through the form to the Document
section then select the Add document 1 button
to add a document.
I'm going to add a document we use for demo
purposes in our quick starts.
In the documentBase64 field I click the Select File button
and find the document I want on my own computer.
The document I choose will be automatically converted
into Base64 format.
Now I can set the document's properties.
First, I'll set a document ID, which can be any integer.
Next, I'll enter the file extension as PDF.
And finally, I'll add the final name of my document.
The values I'm using here are just for this demo.
I'm going to copy the document ID field, though,
because I'll need it later.
If I just want to create an envelope I can send later,
I'm done and I'm ready to execute the API call.
But for this demo, I want to go ahead and send the envelope
so I need to tell API Explorer where to send it.
For that I'll expand the recipient's object
to add a recipient.
DocuSign supports many different kinds
of recipients as well as people who need to sign.
You can add carbon copy recipients, agents, witnesses,
notaries, and more.
I'm just adding a signer here, so I'll
scroll down to the Signer section
and click the Add signer 1 button.
I'll fill in a name and email address for the signer.
I'll also fill in a recipient ID, which can be any integer.
Now I need to set up a place for the signer
to sign the document.
DocuSign calls such places tabs, and to add one
I'm going to open the tabs section for my signer.
You can see that DocuSign offers many different types of tabs
for collecting different information
and supporting various functions.
I'll scroll down to the tab I want.
To include a place for the signer to sign the document,
you need to use a Sign Here tab.
I'll click Add sign here 1 to add a tab.
To link this tab to the document I
attached I need to specify the same document ID I
used when I added the document.
I'll paste in the value I copied earlier.
DocuSign supports two types of tab positioning-- fixed tabs
or anchor tabs.
Fixed tabs are added by providing
the page of the document and the exact coordinates
of the location on that page.
With anchor tabs, you add a particular string
into the document of where you want the tab to appear
and DocuSign automatically inserts the tab
at that location.
API Explorer shows the properties
used for fixed positioning, so I'll use that method.
First I'll need to add the page number for the Sign Here
tab, which I'll set to one.
Next, I'll set the exposition and Y position properties.
The values I'm entering here for exposition and Y position
tell DocuSign where to place the tab in terms of how far
over from the left edge and down the page from the top.
DocuSign uses points to calculate the position.
There are 72 points to an inch, so these numbers
tell DocuSign to put the tab one inch over
from the left and 10 inches down, which will
be one inch from the bottom.
Finally, before I can send the envelope,
I need to add a subject line for the email.
To do that I'll scroll to the email subject property
and fill that in.
That's all I'm choosing to specify for this demo,
but if you expand the various sections you'll see many more
properties of the envelope definition
object you can use for your apps.
These are all documented on the DocuSign Developer Center.
Now I'd like to go back and show you the JSON Editor.
Remember those buttons at the top of the body section?
Here they are again.
Watch what I get when I select the JSON Editor.
All the properties I entered in the form
are now reflected in a text editor,
so I can edit the JSON structure of the API call directly.
As you can see, the JSON Editor is showing the same information
as the JSON viewer does on the right.
And like the JSON viewer, it lets you copy the JSON
to the clipboard.
The JSON editor, however, not only
lets you also edit the JSON itself,
it prompts you for what to add.
See those plus icons?
Select one and you'll see a pop up
of the properties available at that point.
The list is automatically filtered
to remove properties you already used
and those that aren't syntactically valid.
So not only will anything you select be OK,
but you can learn what is and isn't
valid for the structure at that point.
Finally, the Copy and Undo buttons
lets you grab what you've made or undo your mistakes.
Now I'm ready to execute the API call,
except for one last thing--
the envelope status.
You can set it to created, which will simply create and save
the envelope, or sent, which will create and send
the envelope.
I'm setting it to send because I want to see how that works.
Once that's done I'm ready to select Get Response.
API Explorer makes an API request
to the DocuSign e-signature service
and the results are shown below.
API Explorer shows you everything--
the headers, the request body, and the request response.
API Explorer gives you everything
you need to program against the request and response as
needed for your app.
Since this actually executed an API call,
I can check my email to see what the request looks like.
Here's the body of the email I received.
When I select View Documents, DocuSign opens a browser window
with the DocuSign signing experience,
showing the DocuSign sent by my API call.
Now I can sign and complete the process.
Now you've seen how easy it is to use API Explorer to work
with the DocuSign API calls to see how to use them
and what kind of response you get.
I hope this helps you build and troubleshoot
your DocuSign integrations.
Want to know more about DocuSign APIs?
The DocuSign Developer Center contains
guides, how to's, SDKs, sample apps, and lots of resources
to help you learn how to develop integrations within Docusign.
Thanks for watching.
If you're watching from our YouTube channel,
please post questions and comments
below the video or email us developers@docusign.com.