MyDocSafe API Documentation

MyDocSafe's API is reached via HTTP, like most of modern APIs. All requests must be done over TLS. The authentication and general flavor of communication is based on OAuth 2. In order to interact with MyDocSafe in behalf of a user, you must first acquire an access token for that user.

OAuth authentication

Standard OAuth 2 authentication

Step 1
Generate state token - a random string used as XSRF protection and an identifier of the current authentication process. It must be at least 32 bytes long. Use of CSPRNG is advised.

Step 2
Direct the user to a URL with the following format:

Fill the [variables] with the following values:

1. [application key] or "client ID", is a public identifier of your application. you'll receive both an application key and an application secret after creating the application. Please contact us if you don't have your application yet.
2. [state token] is a random string used as XSRF protection and an identifier of the current authentication process. It must be at least 32 bytes long. Use of CSPRNG is advised.
3. [scope requested] is a list of permissions you're asking for from the user. See the section list of scopes for a full list of available scopes that are available.
4. [redirect URI] is the URL to redirect the user to after the user accepted your request.

Step 3
The user will be asked to accept your request. After approval, the user will be redirected to a link with the following format:

Make sure that [state token] is valid, retrieve the [auth code] from the URL.

Step 4
Exchange the [auth code] for the access token using the oauth2/token endpoint.

Standard OAuth 2 with loopback

For the desktop and mobile applications. Same as standard OAuth 2 authentication, but [redirect URI] points at a service listening on client's local machine, for example https://localhost:2222/authentication. you will have to send [auth code] to your server from the desktop application, as you do not want to store the application secret on the client's computer. For the mobile application, you may prefer using app links or similar mechanism. Contact us if you are not sure.

OAuth 2 with waiter

Similar in purpose to OAuth 2 with loopback, but easier to implement. After directing the user to the authorization URL (not to be confused with [redirect URI]), use the oauth2/wait endpoint to retrieve the [auth code]. When generating URL to redirect the user, omit the [redirect URL] variable, so that the user remains on the current page after the authentication.

OAuth token

All requests interacting with MyDocSafe user's accounts must contain an authentication token in HTTP header. In this version of API, simply send Authorization header, containing access token you acquired using oauth2/token endpoint. The header may look like: You may skip the "Bearer" word: Or provide access token in X-AccessToken header instead:

List of scopes

• folder-listing - retrieving a list of folders from the user's account.
• file-listing - retrieving a list of files from the user's account.
• file-upload - uploading files to the user's account.
• create-folders - creating folders in the user's account.
• create-signing-schemas - creating and modifying signing schemas.
• file-signing-request - sending signature requests on user's behalf.
• signed-copies - access to copies of signed documents (only those from signing procesess triggered by your application)

List of requested scopes must be comma-separated.

API responses

We are not providing any GET endpoints for security reasons - according to the RFC 7231, the GET requests should never be used when dealing with sensitive data, like encryption keys. As we wanted to avoid confusion that could be caused by mixing a RESTful approach with a non-RESTful one, our API is not RESTful. All successful responses will have HTTP response code 200, unsuccessful ones - HTTP response code 400. All responses are in json format. The returned json object always contains boolean success, which is true for successful responses and false if an error occured. If error occured, the json object will contain error_code integer and error_message string.

List of error codes

Base API URL

Access to the sandbox environment will be provided on request.

Production environment

OAuth endpoints

JSON objects

Signing parties

Array of objects or single object with the following structure:

• string email_address - e-mail address of signee. Required.
• string phone_number - phone number of signee. Specify only if you want to enable text message verification.
• string personal_message - optional. Signee will see this message in signature request e-mail.
• string thank_you_message - optional. Signee will see this message in signature confirmation e-mail.

Or array of strings containing only e-mail addresses. You can also provide string with single e-mail address instead.

Signing options

JSON object as follows:

• boolean signatureRemoveOriginal - remove original file after signing.
• boolean signatureAutomaticReminder - send automatic reminders about signature request.
• integer signatureAutomaticReminderLimit - limit of automatic reminders.
• boolean signatureEmailBranding - set to true to enable user's branding in e-mail.

Defaults:

• signatureRemoveOriginal - false
• signatureAutomaticReminder - true
• signatureAutomaticReminderLimit - 1
• signatureEmailBranding - false

Signing processes

Array of objects with the following structure:

• string envelope_id - identifier of the signing process.
• boolean is_finished - true if everyone signed the document.
• boolean is_downloadable - true if you set signed_copy_handle to store.

Listing

Array of objects with the following structure:

• integer id - ID of item.
• string type - "folder" or "file".
• string name - name of item.

Companies

Array of objects with the following structure:

• integer id - ID of company.
• string name - name of company.

Notifications

Array of objects with the following structure:

• integer id - ID of notification.
• string name - content of notification.

Signed document retrieval

While creating signing request in behalf of user, you can specify the signed_copy_handle parameter. If you decided for "send" method, our system will perform POST request against URL specified in the signed_copy_param parameter. The POST will contain the following fields:

• envelope_id - identifier of the signing process the document has been attached to.
• file_content - content of the file, unencrypted and unencoded.

After processing the request, your script must return HTTP response code 201 Created. If it won't, or if we are unable to connect to your server for any reason, our system will try to send the request again later. The body of response is ignored.
If you decided for "store" method, we'll encrypt the document with key you provided in the signed_copy_param parameter. you can then use signing/download endpoint to download it. If you'd like to check status of signing processes initiated by your application in behalf of user, or see if there's documents ready for download, use the signing/list endpoint.
The signed document copy is always a pdf file.

Supported document formats

You can upload any file to user's MyDocSafe account, but not all types of files can be signed. Since MyDocSafe is mostly focused on documents, the collection of supported file types contains mostly those commonly used for docuent storage, like PDF, DOC, or JPEG for scanned copies. MyDocSafe signing engine works natively with PDF files, so all non-PDF files are converted to PDF before further processing. It happens automatically and you don't have to trigger it manually.

List of supported extensions:
Encrypted and DRM protected documents are not supported.
If you're using file format that is not supported by MyDocSafe signing engine - contact us.
Keep in mind that in some cases it's not possible to convert given file to PDF without changing it's look and feel a little. Some rare fonts may be replaced with more mundane ones, size of text may change a bit and so on. It's especially true for documents generated by ancient versions of Microsoft Office and files poorly assembled by custom software without following the standards.
We do have plans for non-document signing - music, videos, encryption keys, compiled programs and other binary files - but it's not very high on our current priorities list. If you'd like to use our API or MyDocSafe itself to sign binary files - let us know.

Dedicated application folder

Instead of working with user's folders and files, you may decide to use your dedicated application folder. Each user connected to your application will have unique folder, named after your application. This folder is created only if you're actually using it, by ommiting parameters like parent_id or folder_id in endpoints like file/upload, folder/create or signing/request.

Notifications target override

By specifying HTTP header X-Subuser-Email while calling account endpoints, you can override the default notifications target e-mail for given action. Simply put desired e-mail address in X-Subuser-Email to use.
Notifications target override is currently supported only in signing/request endpoint.

Swagger