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:[application key]&state=[state token]&scope=[scope requested]&redirect_uri=[redirect URI]

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:

[redirect URI]?code=[auth code]&state=[state token]

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:
Authorization: Bearer [access token]
You may skip the "Bearer" word:
Authorization: [access token]
Or provide access token in X-AccessToken header instead:
X-AccessToken: [access token]

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

List of error codes and their descriptions
Error codeDescription
0Required parameter has not been provided.
1Invalid application key.
2Invalid application secret.
3Invalid access token.
4Application not allowed to perform this operation (see: scopes section).
5Folder not found.
6Invalid signed file handling method.
7Invalid encryption key (all encryption keys must be 32 bytes long, printable ASCII characters only).
8TLS required (you provided non-HTTPS redirect URI, singing handler or other URL).
9Invalid URL provided.
10You have no access to item you're trying to manipulate.
11Provided encryption key does not match data you want to decrypt.
12Requested resource is not available yet.
13Provided signing parties object is invalid.
14Could not convert provided file to PDF.
15Unsupported file format.


Access to the sandbox environment will be provided on request.

Production environment

OAuth endpoints

POST /wrapi/v1/oauth2/token


Exchange authorization token for permanent access token, claiming client for application.


  • client_id - your application key.
  • client_secret - your application secret.
  • code - authorization code received from redirect URI or oauth2/wait endpoint.


  • boolean success - true if request succeeded.
  • string access_token - access token you may use for requests that interact with users' account.
POST /wrapi/v1/oauth2/wait


Retrieves authentication token you may exchange for access token. Useful if you don't want to use redirect URI method.


  • client_id - your application key.
  • client_secret - your application secret.
  • state - state token you previously generated.


  • boolean success - true if request succeeded.
  • string state - your state token.
  • boolean client_authorized - true if client authorized your application, false if he didn't yet.
  • string code - authentication code you may exchange. Present if client_authorized is true.

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.


  • 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.


Array of objects with the following structure:

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


Array of objects with the following structure:

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


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:
jpg, jpeg, png, gif, bmp, pdf, doc, dot, docx, docm, dotx, dotm, docb, xls, xlt, xlm, xlsx, xlsm, xltx, xltm, xlsb, xla, xlam, xll, xlw, ppt, pot, pps, pptx, pptm, potx, potm, ppam, ppsx, ppsm, sldx, sldm, pdf, txt, rtf
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.