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:

https://app.mydocsafe.com/authorize/?client_id=[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.

Base API URL

Access to the sandbox environment will be provided on request.

Production environment

https://app.mydocsafe.com/wrapi/v1/

OAuth endpoints

POST /wrapi/v1/oauth2/token

Description

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

Parameters

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

Response

  • 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

Description

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

Parameters

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

Response

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

Account interaction endpoints

For calling these, you will need the user's access token.

POST /wrapi/v1/folder/create

Description

Creates folder in user's account. Requires create-folders scope.

Parameters

  • parent_id - integer, ID of parent element. Leave it empty or set to false to create folder in your application's dedicated folder.
  • folder_name - name of new folder.

Response

  • boolean success - true if request succeeded.
  • integer folder_id - ID of your new folder.
POST /wrapi/v1/file/upload

Description

Uploads the file specified with standart multipart/form-data method to the selected folder. Requires file-upload scope.

Parameters

  • parent_id - integer, ID of parent element. Leave it empty or set to false to upload file into your application's dedicated folder.

Response

  • boolean success - true if request succeeded.
  • integer file_id - ID of your uploaded file.

Note:

Only one file is processed

Code sample:

$parent_folder_id = 12345; // please, use your folder id
$token = '8fbc3a44b2d1da94ebc2321e123a0adcfa740e17e9ccc2cd79b746031c6e41'; // please, use your token
$file_name = '/home/usr/1.pdf'; // please, use your file name

$handler = curl_init();
curl_setopt($handler, CURLOPT_HTTPHEADER, array('authorization: Bearer ' . $token));
curl_setopt($handler, CURLOPT_URL, 'https://app.mydocsafe.com/wrapi/v1/file/upload?parent_id=' . $parent_folder_id);
curl_setopt($handler, CURLOPT_POST, true);
curl_setopt($handler, CURLOPT_SAFE_UPLOAD, false);
curl_setopt($handler, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($handler, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($handler, CURLOPT_RETURNTRANSFER, 1);
$args['file'] = new CurlFile($file_name, 'application/pdf');
curl_setopt($handler, CURLOPT_POSTFIELDS, $args);
$response = curl_exec($handler);
curl_close($handler);
							
POST /wrapi/v1/signing/request

Description

Sends the signing request in behalf of user. Requires file-signing-request scope. There's two signing methods available in API: fieldless and signing schema based. Only the fieldless method is fully documented in current version of API documentation. While sending file for signing, use the multipart/form-data encoding.

Parameters

  • parent_id - copy of provided file will be uploaded to user's account. Set the parent_id to ID of the folder you'd like to create document in. Leave empty or set to false to use your application's folder.
  • file_name - name of file you want to sign. Optional if use_template is true, required otherwise.
  • file_content - content of file, unencoded and unencrypted. Required if use_template is not true.
  • parties - string containing single e-mail address or parties JSON string. Leave empty or set to false to send signign request only to the owner of account - owner's email will be fetched automatically.
  • options - JSON string with signing options. Leave empty or set to false to use defaults.
  • signed_copy_handle - string, may be one of "send", "store" or "ignore". This parameters lets you decide how to handle the signed copy of document, when the signing process is done. The "ignore" value is equivalent of ommiting this parameter or setting it to null / false - we will not provide you with the copy of document. The "send" option will send the copy of signed file to URL you specified in the signed_copy_param parameter (see: signed document retrieval section). The "store" option will encrypt the signed copy with encryption key specified in the signed_copy_param parameter - you can download it later using signing/download endpoint.
  • signed_copy_param - if the signed_copy_handle is "send", this parameter should contain HTTPS URL (see: signed document retrieval section). If signed_copy_handle is "store", this parameter should contain encryption key, 32 bytes, ASCII printable characters (see: signing/download endpoint).
  • use_template - boolean, set to true to use template signing. Defaults to false.
  • template_path - string, path to or name of template you want to use. Required and used if use_template is set to true.
  • template_variables - JSON string used to fill the form template. Required and used if use_template is set to true.

Response

  • boolean success - true if request succeeded.
  • string envelope_id - identifier of the signing process.
POST /wrapi/v1/signing/download

Description

Download signed copy of the document. you can check if you have any pending documents to download using the signing/list endpoint. Requires signed-copies scope.

Parameters

Response

  • boolean success - true if request succeeded.
  • string file_content - unencrypted, base64-encoded PDF file content.
POST /wrapi/v1/signing/list

Description

Returns list of the signing processes and their statuses. Only shows signing processes trigered by your application. Requires create-signing-schemas scope.

Parameters

  • filter - string, optional, may be one of: "finished" (only the finished signing processes are returned), "not-downloaded" (finished, with signed copy waiting for you), "pending" (only pending signatures).

Response

  • boolean success - true if request succeeded.
  • array signing_processes - JSON object "signing processes".
POST /wrapi/v1/listing

Description

Returns list of items in given user's folder. Requires folder-listing and/or file-listing scopes. If you have only folder-listing scope, you will not receive user's file names and IDs in response. If you have only file-listing scope, you will not be able specify folder_id parameter, being limited to your application's dedicated folder, but you will see both files and folders inside it.

Parameters

  • folder_id - integer, ID of folder you'd like to get contents from. Leave empty, set to null or false to retrieve the contents of user's root folder, unless app_folder boolean is true.
  • app_folder - boolean, if true we will ignore the folder_id (if it's specified) and show contents of your dedicated application folder.

Response

  • boolean success - true if request succeeded.
  • array listing - JSON object "listing".
POST /wrapi/v1/companies/list

Description

Returns list of companies user have access to in JSON format.

Parameters

    None.

Response

  • boolean success - true if request succeeded.
  • array companies - JSON object "companies".
POST /wrapi/v1/notifications

Description

Returns list of notifications for user in JSON format.

Parameters

    None.

Response

  • boolean success - true if request succeeded.
  • array notifications - JSON object "notifications".
POST /wrapi/v1/portals/sendfile

Description

Creates new user portal related to specified target user in API user's company if it doesn't exist yet and uploads new file into it.

Parameters

  • company_id - integer, optional, ID of user's company. Defaults to first company available if not specified.
  • target_email - string, required, e-mail address of person you want to send file to.
  • target_name - string, optional, name of new client portal. Defaults to target_email if not specified.
  • file_name - string, required, name of file.
  • file_content - binary, required, content of file.
  • message - string, optional, message that will be attached to portal invitation.
  • send_notification - boolean, optional, defaults to true. If set to false, user will not receive notification about file.

Response

  • boolean success - true if request succeeded.
  • integer item_id - ID of uploaded document.

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