Partner API Documentation

Basics and Principles

The integration mode was created in order to give end users access to SMASHDOCs directly from their partner’s system without the need for an additional login or user syncing process.

Overview over SMASHDOCs

SMASHDOCs is a modern web application that enables teams to write and collaboratively review documents easier and faster than ever.

New documents are always created in draft mode. A SMASHDOC is composed of paragraphs, images and tables just like in any other document editor.

As soon as users want to collaborate or share their document, they must start the review mode which enables them to invite other users to the document. Once a SMASHDOC is in review mode, users with appropriate rights are able to suggest changes, add comments, or as questions. Unlike other solutions, all changes within a SMASHDOC are tracked, which can then be reviewed and accepted or declined.

In order to manage a user’s permissions in the document, there are four different roles that a user can be in:

  • Reader (read the document and conversations, create bookmarks)
  • Commenter (all Reader permissions + create new comments, questions, and comment on other conversations)
  • Editor (all Commenter permissions + edit and move sections)
  • Approver (all Editor permissions + decide on content).

Authentication

Data is passed between the partner’s backend and the SMASHDOCs backend over an authorized connection. The SMASHDOCs backend is passive; acting only when called upon by the partner system to create, open and list documents.

Authentication is based on the use of a JSON Web Token (JWT). The JWT is passed as a Bearer Token in the authorization field of the headers in each API call. The following fields are required in the data-part of the JWT:

FIELD TYPE DESCRIPTION
iat integer Issued At Claim: UTC timestamp at the time of issue of JWT auth request.
iss string Issuer Claim: user id in the partner system.
jti string JWT ID Claim: unique identifier for the JWT.

Signing of the JWT can be done with the HS256, HS384 or HS512 method, where the client-secret is used as secret key. Together with the client-id, that is passed in the x-client-id header field, the authentication is complete.

Code example: JWT in Python

import jwt
import uuid
import datetime

# provided client-secret by SMASHDOCs
client_secret = '32284ebdc5b8ea867058155b6ebcd7e0f9b0ed0ce2953b0451d9e6dbc9a68e70' # example

# user_id which issues the provisioning request
user_id = '5813099d5cb91899eea6da05' # example

jwt_payload = {
    'iat': int(datetime.datetime.now().timestamp()),
    'iss': user_id,
    'jti': str(uuid.uuid4())
}
token = jwt.encode(payload=jwt_payload, key=client_secret, algorithm="HS256")
bearer_token = "Bearer {token}".format(token=token.decode('ascii'))
print(bearer_token)

Further information about the JWT can be found at https://jwt.io/ .

Important

If you have received you SMASHDOCS-API credentials before November 2016 and you want to use JWT, please write us an email to support@smashdocs.net.

Users, Rights and Roles

The partner is required to manage all users, rights and roles within their own system. SMASHDOCs, additionally, makes its document rights and role management available in order for the partner to manage in-document permissions. Because SMASHDOCs is not managing nor syncing permissions between it and the partner system, all user and permission information needs to be passed to the SMASHDOCs API when opening or creating a document. This ensures that user access rights and permissions remain up to date within SMASHDOCs. To reiterate, when opening a document, no external API calls will be made from SMASHDOCs in order to verify document access rights. The responsibility lies solely with the partner to ensure that only allowed users can open a SMASHDOC.

API Functions

Headers

With JWT-based authentication:

KEY VALUE USAGE
x-client-id {client id} all API-calls
authorization Bearer {JWT} all API-calls
content-type application/json POST API-calls except /partner/imports/word/upload
content-type multipart/form-data /partner/imports/word/upload

With user / password authentication:

KEY VALUE USAGE
x-api-key {api key} all API-calls
content-type application/json POST API-calls except /partner/imports/word/upload
content-type multipart/form-data /partner/imports/word/upload
authorization {admin access token} all API-calls except /partner/authenticate

Errorcodes

CODE MEANING
401 Authentication required Authorization is missing or invalid
402 Payment required
If the pricing model “freemium” is enabled the API will return a HTTP 402
to notify the partner, that the limit was hit.
A partner should react to this error with an upgrade pricing model page
403 Forbiden API-Key or Client-ID missig or insufficient rights
403 Not Found Requested resource not found
412 Precondition failed Missing or wrong request parameters
403 Request Entity Too Large Uploaded filesize is exceeding limit

Creating empty Documents

Example: POST /partner/documents/create

When a user creates a document, the partner system authenticates itself against the SMASHDOCs API and calls the create document API endpoint (POST /partner/documents/create/).

The following information must be passed along in the API call:

  • userId - id of the user in the partner system
  • email - the users email address (max. 150 chars)
  • firstname (max. 150 chars)
  • lastname (max. 150 chars)
  • company - the users company name (max. 150 chars)
  • title - the document title (max. 200 chars)
  • description (max. 400 chars)
  • userRole (SMASHDOCs role)
  • groupId (partner system group to which the document will belong to)

Optional fields:

  • sectionHistory - allowed to see section history (SMASHDOCs right)
  • supplemental - information which is stored by SMASHDOCs but never evaluated. This field can be used to save and retrieve partner specific information (max. 400 chars)
  • status - gives possiblity to create the document in draft (default) or review mode.

The SMASHDOCs backend stores this data and generates a one time password token. If the user (referenced by user id) is already in the database, the user’s information will be overwritten by the new values. If it is the case that a user’s name or email have changed, all of these values can be updated. Their user id however cannot be changed.

Hint

The properties firstname, lastname, company and email address as well as the role can be changed with the open document api call. However the user id is the primary key and cannot be changed.

After the document has been created, the document access link will be returned. The document will be shown in the user’s browser, when he is redirected to the document access link.

If a document is created in draft mode, it is only visible for the creator. As soon as the document is set to review mode by the user or via partner API, it will be visible for all members of the group and can be opened by users who belong to the group.

Opening Documents

Example: POST /partner/documents/{id}

Opening documents follows nearly the same logic as the document creation API call. Again, in order to ensure that user information stays up to date, all relevant user information needs to be sent with the request. The provided user information will then be updated and the current document access link returned. The partner system should then redirect the user to the document access link via an HTTP 302 status code.

Hint

The document access link expires after 1 minute and can just be used once to open the SMASHDOC. If you need to open a SMASHDOC again, it needs to be opened again via the partner API.

Importing Word Documents

Example: POST /partner/imports/word/upload

Creating a SMASHDOCs document out of a MS Word file (.docx only) works almost similar to the create document api call. Besides providing the the metadata of the document and the user information the additional MS Word file is required. The response contains the document access link.

In order to send the metadata, user information and MS Word file in one single request, the request needs to be sent as multipart/form-data (content-type) which contains the two fields file and data:

  • file - docx file
  • data - json string which contains all fields that are also used in /partner/documents/create

Important

Right now only .docx word files can be processed by the API

Pass style mapping

If a word-file using paragraph styles should be imported, it is possible to pass a style mapping. This style mapping is an object containing the information, which SMASHDOCs section type should be created for a certain Word paragraph style.

The key for a mapping entry is the Word paragraph style. For self-created styles, the exact name of the style has to be used as key. Existing standard word styles are always translated automatically when opening the file in a Word version with a different language. Therefore the Word native paragraph styles come out always in english matching the following list:

  • heading 1
  • heading 2
  • heading 3
  • heading 4
  • heading 5
  • heading 6
  • caption

The value for a mapping entry is an object that describes the target format in SMASHDOCs via the following fields:

key possible value description
textType paragraph normal text, auto-recognizes also lists
paragraph-ol numbered paragraph
heading heading
heading-ol numbered heading
caption image caption
list-ol numbered list
list-ul bullet list
level integer between 0 and 5 outline, indent or counting level for paragraph, paragraph-ol, heading and heading-ol

Code example: multipart upload in Python

import requests
import json

# This example uses jwt auth headers. The x-api-key + authentication method however is also supported
headers_jwt_auth = {
   'x-client-id': '1a01ad73c4c6d0d76605d01a30e6e31fe7f8ba6b4b28dc73342f9acfb43efc61',
   'authorization': 'Bearer 1b19c22435a0b5517ac3f0389511d9eb8ab7881c0ce13d69d42fabc28a5a56bb'
}

data = {
         "user": {
             "email": "steven.miller@yourcompany.com",
             "firstname": "Steven",
             "lastname": "Miller",
             "userId": "764ea18872a34337",
             "company": "yourcompany"
         },
         "title": "my first SMASHDOCs document",
         "description": "",
         "groupId": "85c2602653b7c",
         "userRole": "approver",
         "mapping": {
             "List Paragraph": {
                 "textType": "paragraph", "level": 0
             },
             "heading 1": {
                 "textType": "heading-ol", "level": 0
             },
             "heading 2": {
                 "textType": "heading-ol", "level": 1
             },
             "My Individual style": {
                 "textType": "heading", "level": 0
             }
         }

files = {
   'data': (None, json.dumps(data), 'application/json'),
   'file': ('sample.docx', open('sample.docx', 'rb'), 'application/octet-stream'),
}

base_url = 'https://partner-api.smashdocs.net'
result = requests.post('{base_url}/partner/imports/word/upload'.format(base_url),
                        files=files,  headers=headers_jwt_auth, verify=False)

print(result)

Importing XML Documents

Example: POST /partner/imports/sdxml/upload

SMASHDOCs can be created by uploading a SMASHDOCs XML file (SDXML) and is working similar to importing word documents. (see Importing Word Documents). The SDXML import endpoint takes a zip file containing the SDXML file (sd.xml) as well as the images referenced in the XML (please see the example how to build the zip file). The DTD of the SDXML and more detailed documentation can be found here xml.html#sd-xml-documentation. The response contains the document access link.

In order to send the metadata, user information and the SDXML zip file in one single request, the request needs to be sent as multipart/form-data (content-type) which contains the two fields file and data:

  • file - sd xml zip file
  • data - json string which contains all fields that are also used in /partner/documents/create

An example of uploading multipart/form-data can be found also in section Importing Word Documents.

Exporting Documents

Exporting Documents to SDXML

Example: POST /partner/documents/{id}/export/sdxml

A document can be exported to a SDXML-zip-file. This is a zip that contains one xml-file sd.xml and a folder images. The same structure is accepted in the import xml api call.

In the request payload, the field userId must be set in the request payload. The language for Image captions like “Figure 3” will be taken from the user’s language.

Exporting Documents to zipped html

Example: POST /partner/documents/{id}/export/html

A document can be exported to a zipped html file. The zip-file contains index.html and a folder images.

In the request payload, the field userId must be set in the request payload. The language for Image captions like “Figure 3” will be taken from the user’s language.

In order to export the document with history and conversations, there are two optional fields, that can be set:

mode must be set to one of the following fields:

mode description
final No redline, no conversations
news Redline view, new changes and conversation posts are highlighted
allInOne Redline view, full history per section (changes & conversations)
redlineAndPending All conversations with status ‘pending’ including all posts

onlyPublic (boolean) exports only conversations that are visible for all users.

Getting available word templates

Example: GET /partner/templates/word

An export to word requires a word template. The GET /partner/templates/word API-endpoint returns a list of available word templates with id, name and description.

Exporting Documents to word

Example: POST /partner/documents/{id}/export/word

Exporting a document to word can be done via the /partner/documents/{id}/export/word API-endpoint.

To execute the export, three fields are required in the request payload. The userId defines, for which user the export is done. A template can be selected via templateId.

Additional options are offered to be set with the settings-object:

  • language can be de_DE or en_EN
  • imageCaption sets, whether image captions should be shown
  • tableCaption sets, whether table captions should be shown
  • textToc sets, whether a table of contents should be generated
  • imageToc sets, whether a list of images should be generated (only with imageCaption=true)
  • tableToc sets, whether a table of contents should be generated (only with tableCaption=true)

Exporting Documents to Parsx XML

Example: POST /partner/documents/{id}/export/parsx

A document can be exported to a Parsx-zip-file. This is a zip that contains one xml-file parsx.xml and a folder images. The same structure is accepted in the import xml api call.

In the request payload, the field userId must be set in the request payload. The language for Image captions like “Figure 3” will be taken from the user’s language. ~

Listing Documents

Example: GET /partner/documents/list

To fetch all documents belonging to a specific group, 3 different variations of the API call exist. They are as follows:

  • sending the user id and group id (partner system): for documents belonging to the group, receive all draft documents (documents have not been shared yet) that are created by the given user and all review documents (shared documents).
  • sending just the group id: receive just the review documents for the given group
  • sending just the user id: receive all draft documents from all groups to which the user belongs to (but no shared docs) that have been created by the user.

The user id can be sent either as userId (that was given when calling create or open document for user) or as userIdSD (id of user in SMASHDOCS system)

Note that the partner system is responsible for the management and creation of groups and their corresponding group id. The SMASHDOCs API only stores the group id upon document creation in order to provide proper document listings.

Get Unseen Changes Count

Example: GET /partner/documents/unseen/count

The count of documents with unseen changes in section content or conversations for a user can be fetched. Returned are counts of:

  • documents with changes in section content
  • documents with changes in conversation
  • documents with any changes

These counts are returned for the total amount of documents and itemised for each group.

Listing Documents with unseen changes

Example: GET /partner/documents/unseen/list

For documents with unseen changes in section content or conversations for a user, a list can be fetched. The fields in the list are the same as in the Document Listing function shown above.

Getting Information for a single Document

Example: GET /partner/documents/{id}

The properties of a single document can be fetched in order to check for example whether it is archived or to check the creatorId. The fields are the same as in result items of the Document Listing function shown above. In order to receive the fields hasOpenedDocument, hasUnreadSctionChanges and hasUnreadConversationChanges filled for a specific user, his id can be sent as a query parameter.

Duplicating documents

Example: POST /partner/documents/{id}/duplicate

Documents can be duplicated for a user who will be stored as creator of the document’s copy. A document can only be duplicated, if the document is:

  • in review mode or, if it is in draft mode, the user is creator of the source document
  • not archived (see section below)

Archiving documents

Example: POST /partner/documents/{id}/archive

Example: POST /partner/documents/{id}/unarchive

The SMASHDOCs partner API offers the possiblity to mark a document as archived. Afterwards, it will no more be possible to open this document for a user unless it is reactivated (unarchive). The choice of documents shown in the document list will not be influenced by this flag.

Deleting draft documents

Example: DELETE /partner/documents/{id}

Only draft documents can be deleted via the partner API. Review documents cannot be deleted because more than one user can have access to them. SMASHDOCs wants to make sure that every user understands what has been changed at a document. This is why there is no delete for review documents. However one can use the archive (Archiving documents) function to hide documents from users.

Updating document metadata

Example: POST /partner/documents/{id}/metadata

After creating or importing a document the metadata can also be changed by using this API endpoint. Metadata fileds are e.g. document title, description, filename, …. Tags can also be set as metadata. Please note that tags are always overwritten.

Setting a document to review mode

Example: POST /partner/documents/{id}/review

Via this API endpoint, a document can be set to review mode. This enables other users, besides the creator, to open the document.

Examples

POST /users/authenticate (deprecated - will be removed by end of Q1/17)

Use JWT Authentication instead.

REQUEST:

URL: https://partner-api.smashdocs.net/users/authenticate
METHOD: POST
Headers:
    x-api-key: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    content-type: application/json

Payload:
    {"email": "examplepartnersu@smashdocs.net",
    "password": "abcdefghij"}
RESPONSE:

{
  "userId": "684b6774-4cdd-4434-b4ee-f8c02cad4b05",
  "refreshToken": "9aa42ed5faccf0db133ed0352c05a35d11d455f2947",
  "accessToken": "85ab1d31bfb4ae3f2d90fb8fafbc0421490f58bee6a"
}

POST /partner/authenticate

Use JWT Authentication instead.

REQUEST:

URL: https://partner-api.smashdocs.net/partner/authenticate
METHOD: POST
Headers:
    x-api-key: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    content-type: application/json

Payload:
    {"email": "examplepartnersu@smashdocs.net",
    "password": "abcdefghij"}
RESPONSE:

{
  "userId": "684b6774-4cdd-4434-b4ee-f8c02cad4b05",
  "adminAccessToken": "85ab1d31bfb4ae3f2d90fb8fafbc0421490f58bee6a"
}

POST /partner/documents/create

Description: Creating empty Documents

Important

Since Version 1.2.3.1 the properties url and userAccessToken are no longer returned in the response

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/create
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiOGI1ZWZiNGYtNTg1Ni00NTcxLTk4NGYtMmM1NzNiZmIyMmI1IiwiaWF0IjoxNDc2MjcyOTI0fQ.OHQdEyOQdO_Y-9n-X9RoL_1_TuBsBrvgh3ijRPBSExw

Payload:
    {"user": {
        "email": "steven.miller@yourcompany.com",
        "firstname": "Steven",
        "lastname": "Miller",
        "userId": "764ea18872a34337",
        "company": "yourcompany"
    },
    "title": "my first SMASHDOCs document",
    "description": "",
    "groupId": "85c2602653b7c",
    "userRole": "approver",
    "sectionHistory": true,
    "supplemental": "partner specific information",
    "status": "draft"
    }
RESPONSE:

{
    "documentAccessLink": "https://partner.smashdocs.net/#/document/8e6875cb-5cd2-4178-8ad4-d77b92173bf9
                           &otpt=c938609e2bfc3e8049346a7fef96506aab6babc2e918dd9787a1ae7ce70b3fb1",
    "userIdSD": "b01b8477-01aa-49fe-8cfb-3d3cb00fac1b",
    "documentId": "8e6875cb-5cd2-4178-8ad4-d77b92173bf9"
}

POST /partner/documents/{id}

Description: Opening Documents

Important

Since Version 1.2.3.1 the properties url and userAccessToken are no longer returned in the response

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/8e6875cb-5cd2-4178-8ad4-d77b92173bf9
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiMjY1Y2RlYjItMjg2OC00NGJlLTg1YjctYTVlZDE1YTJmNjQxIiwiaWF0IjoxNDc2MjczODQyfQ.JB3NK40RoW8HdsHQhELSjdDDQ5r94i8ZfEhyoKFfieQ

Payload:
    {"user": {
        "email": "steven.miller@yourcompany.com",
        "firstname": "Steven",
        "lastname": "Miller",
        "userId": "764ea18872a34337",
        "company": "yourcompany"
    },
    "userRole": "approver",
    "sectionHistory": true
    }
RESPONSE:

{
    "documentAccessLink": "https://partner.smashdocs.net/#/document/8e6875cb-5cd2-4178-8ad4-d77b92173bf9
                           &otpt=c938609e2bfc3e8049346a7fef96506aab6babc2e918dd9787a1ae7ce70b3fb1",
    "userIdSD": "b01b8477-01aa-49fe-8cfb-3d3cb00fac1b",
    "documentId": "8e6875cb-5cd2-4178-8ad4-d77b92173bf9"
}

POST /partner/documents/{id}/metadata

Description: Updating document metadata

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/8e6875cb-5cd2-4178-8ad4-d77b92173bf9/metadata
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiZDlhYTk4YmYtZjYzZS00MmJmLWFhMDgtNTI2YmNhYTAxNjNlIiwiaWF0IjoxNDc2MjczODQ2fQ.VkxUzVOiPI2eV9Ir-O8ZykZpbHOWVMr2GT4ZiyrWG2w

Payload:
    {
        "title": "new document title",
        "description": "new document description",
        "subtitle": "document subtitle",
        "filename": "document filename",
        "footer": "document footer",
        "tags": ["tag1", "tag2"],
        "supplemental": "partner specific information"
    }
RESPONSE:

{
}

POST /partner/documents/{id}/export/sdxml

Description: Exporting Documents to SDXML

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/8e6875cb-5cd2-4178-8ad4-d77b92173bf9/export/sdxml
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiMjY1Y2RlYjItMjg2OC00NGJlLTg1YjctYTVlZDE1YTJmNjQxIiwiaWF0IjoxNDc2MjczODQyfQ.JB3NK40RoW8HdsHQhELSjdDDQ5r94i8ZfEhyoKFfieQ

Payload:
    {
        "userId": "764ea18872a34337"
    }
RESPONSE:

     << SDXML - FILE >>

POST /partner/documents/{id}/export/parsx

Description: Exporting Documents to Parsx XML

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/8e6875cb-5cd2-4178-8ad4-d77b92173bf9/export/parsx
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiMjY1Y2RlYjItMjg2OC00NGJlLTg1YjctYTVlZDE1YTJmNjQxIiwiaWF0IjoxNDc2MjczODQyfQ.JB3NK40RoW8HdsHQhELSjdDDQ5r94i8ZfEhyoKFfieQ

Payload:
    {
        "userId": "764ea18872a34337"
    }
RESPONSE:

     << parsx-zip - FILE >>

POST /partner/documents/{id}/export/html

Description: Exporting Documents to zipped html

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/8e6875cb-5cd2-4178-8ad4-d77b92173bf9/export/html
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiMjY1Y2RlYjItMjg2OC00NGJlLTg1YjctYTVlZDE1YTJmNjQxIiwiaWF0IjoxNDc2MjczODQyfQ.JB3NK40RoW8HdsHQhELSjdDDQ5r94i8ZfEhyoKFfieQ

Payload:
    {
        "userId": "764ea18872a34337"
    }
RESPONSE:

     << html-zip - FILE >>

GET /partner/templates/word

Description: Getting available word templates

REQUEST:

URL: https://partner-api.smashdocs.net/partner/templates/word
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiMjY1Y2RlYjItMjg2OC00NGJlLTg1YjctYTVlZDE1YTJmNjQxIiwiaWF0IjoxNDc2MjczODQyfQ.JB3NK40RoW8HdsHQhELSjdDDQ5r94i8ZfEhyoKFfieQ
RESPONSE:
[
 {
   "id": "f6298fb4-299a-4959-9e0d-969c7312037f"
   "name": "Standard",
   "description": "Standard word template",
 },
 {
   "id": "7c919d7f-7447-403c-8ba3-e62a77949b22"
   "name": "Contract",
   "description": "word template for contracts",
 }
]

POST /partner/documents/{id}/export/word

Description: Exporting Documents to word

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/8e6875cb-5cd2-4178-8ad4-d77b92173bf9/export/word
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiMjY1Y2RlYjItMjg2OC00NGJlLTg1YjctYTVlZDE1YTJmNjQxIiwiaWF0IjoxNDc2MjczODQyfQ.JB3NK40RoW8HdsHQhELSjdDDQ5r94i8ZfEhyoKFfieQ

Payload:
    {
        "userId": "764ea18872a34337",
        "templateId": "f6298fb4-299a-4959-9e0d-969c7312037f",
        "settings": {
           "textToc": true,
           "imageToc": true,
           "tableToc": true,
           "imageCaption": true,
           "tableCaption": true,
           "language": "en_EN"
        }
    }
RESPONSE:

     << word - FILE >>

GET /partner/documents/list

Description: Listing Documents

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/list?groupId=85c2602653b7c
METHOD: GET
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiZDlhYTk4YmYtZjYzZS00MmJmLWFhMDgtNTI2YmNhYTAxNjNlIiwiaWF0IjoxNDc2MjczODQ2fQ.VkxUzVOiPI2eV9Ir-O8ZykZpbHOWVMr2GT4ZiyrWG2w
RESPONSE:

[
  {
     "id": "68eb95cb-2c86-4472-b4a7-5fb5fc93a9f9",
     "title": "test2",
     "subtitle": "document subtitle",
     "description": "document description",
     "tags": ["tag1", "tag2"],
     "supplemental": "partner specific information"
     "creatorIdSD": "b89d898d-c51a-4912-909f-e652b511d023",
     "creatorId": "764ea18872a34337",
     "status": "review",
     "createdDate": 1481014475,
     "hasUnreadSectionChanges": false,
     "hasUnreadConversationChanges": false,
     "hasOpenedDocument": false,
     "archived": false,
     "groupId": "group9"
  }
]

GET /partner/documents/unseen/count

Description: Get Unseen Changes Count

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/unseen/count?userId=764ea18872a34337
METHOD: GET
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiNDQyNjNlMWYtYzY2NS00NDYyLWE5MjctYTBjYWM5MDFjOTAyIiwiaWF0IjoxNDc2Mjc0MzM1fQ.tslWwKIpRR4mPpkY_r1R09V6QSdzTsnQSinH3CcjKfM
RESPONSE:

{
  "numWithAnyChange": 2,
  "numWithConversationChange": 1,
  "numWithSectionChange": 1
  "groups": [
    {
      "numWithAnyChange": 1,
      "numWithConversationChange": 0,
      "numWithSectionChange": 1,
      "groupId": "group8"
    },
    {
      "numWithAnyChange": 1,
      "numWithConversationChange": 1,
      "numWithSectionChange": 0,
      "groupId": "group9"
    }
  ],
}

GET /partner/documents/unseen/list

Description: Listing Documents with unseen changes

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/unseen/list?userId=764ea18872a34337
METHOD: GET
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiMDM0Y2YxYzgtODcyZi00MjZhLTk1NGEtZmE4ZGE3ZWJkNmNlIiwiaWF0IjoxNDc2Mjc0NTg0fQ.1aktbLdwbRSR-4dVPN31hRFZlV0hf_AaGVCIEJZOcLQ
RESPONSE:
[
  {
     "id": "68eb95cb-2c86-4472-b4a7-5fb5fc93a9f9",
     "title": "test2",
     "subtitle": "document subtitle",
     "description": "document description",
     "tags": ["tag1", "tag2"],
     "supplemental": "partner specific information"
     "creatorIdSD": "b89d898d-c51a-4912-909f-e652b511d023",
     "creatorId": "764ea18872a34337",
     "status": "review",
     "createdDate": 1481014475,
     "hasUnreadSectionChanges": false,
     "hasUnreadConversationChanges": false,
     "hasOpenedDocument": false,
     "archived": false,
     "groupId": "group9"
  },
  {
     "id": "b75b6641-a191-407e-a899-505d6aa5b01b",
     "title": "test1",
     "subtitle": "document subtitle",
     "description": "document description",
     "tags": ["tag1", "tag2"],
     "supplemental": "partner specific information"
     "creatorIdSD": "b89d898d-c51a-4912-909f-e652b511d023",
     "creatorId": "764ea18872a34337",
     "status": "review",
     "createdDate": 1481014475,
     "hasUnreadSectionChanges": false,
     "hasUnreadConversationChanges": false,
     "hasOpenedDocument": false,
     "archived": false,
     "groupId": "group8"
  }
]

POST /partner/documents/{id}/duplicate

Description: Duplicating Documents

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/2089a1dd-4b17-4694-a21c-e85f292003f4/duplicate
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiOWJhMWQ4NTQtOGU4OS00YjU2LWI4YWQtMGUyNzgwNzU4OTQyIiwiaWF0IjoxNDc2Mjc0NjYxfQ.Db2O2-s1hv3fpldQKz46ZRkjrlsJoVAIZPHyaCm6pz8

Payload:
{
  "title": "copy of document",
  "description": "how to duplicate a document",
  "creatorUserId": "764ea18872a34337"
}
RESPONSE:
{
  "documentId": "8b3c409f-24c3-440f-8ad6-cc2dd316f7ab"
}

POST /partner/documents/{id}/archive

Description: Archiving documents

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/8e6875cb-5cd2-4178-8ad4-d77b92173bf9/archive
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiNWQ5YjhmZjMtOGQ0ZC00NTY0LTg1ZjUtZWY4NzVlNzdiMzFiIiwiaWF0IjoxNDc2Mjc0NzA2fQ.tojNGwRD3n-kvz3UmSUASQRFzdz6z2niRtq8pFZZlC8
RESPONSE:

no response

POST /partner/documents/{id}/unarchive

Description: Archiving documents

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/8e6875cb-5cd2-4178-8ad4-d77b92173bf9/unarchive
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiYjQ2MThmYWEtZjIwYi00YjJjLTk4MDUtYzY1MDQ1ZDRhYTY3IiwiaWF0IjoxNDc2Mjc0NzMyfQ.iAJnIDT7wvW17QSTErGea0_GyU8o_SGKK60GroLRu_k
RESPONSE:

no response

DELETE /partner/documents/{id}

Description: Deleting draft documents

Deletes the document if its in draft mode. Success is indicated by HTTP 200. The endpoint will return HTTP 400 when document is in review mode. Review documents cannot be deleted - please use the archive function.

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/68eb95cb-2c86-4472-b4a7-5fb5fc93a9f9
METHOD: DELETE
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiYzJmZWUxN2YtNzQ2Yy00YjdlLTliYWMtMWFlYjMwYjBjNjRiIiwiaWF0IjoxNDc2Mjc0ODIyfQ.dSXh7GRr6HRmZv6xn4hxlHF39em5qiYVRn2-A0EZ1Pc
RESPONSE:
{
}

POST /partner/documents/{id}/review

Description: Setting a document to review mode

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/8e6875cb-5cd2-4178-8ad4-d77b92173bf9/review
METHOD: POST
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiYjQ2MThmYWEtZjIwYi00YjJjLTk4MDUtYzY1MDQ1ZDRhYTY3IiwiaWF0IjoxNDc2Mjc0NzMyfQ.iAJnIDT7wvW17QSTErGea0_GyU8o_SGKK60GroLRu_k
RESPONSE:

no response

GET /partner/documents/{id}

Description: Getting Information for a single Document

Hint

The properties hasOpenedDocument, hasUnreadConversationChanges and hasUnreadSectionChanges are dependent of a user. By adding the query parameter ?userId=<userId> it is possible to get the status of a document for a specific user

REQUEST:

URL: https://partner-api.smashdocs.net/partner/documents/68eb95cb-2c86-4472-b4a7-5fb5fc93a9f9
METHOD: GET
Headers:
    content-type: application/json
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiYzJmZWUxN2YtNzQ2Yy00YjdlLTliYWMtMWFlYjMwYjBjNjRiIiwiaWF0IjoxNDc2Mjc0ODIyfQ.dSXh7GRr6HRmZv6xn4hxlHF39em5qiYVRn2-A0EZ1Pc
RESPONSE:
{
    "id": "68eb95cb-2c86-4472-b4a7-5fb5fc93a9f9",
    "title": "test2",
    "subtitle": "document subtitle",
    "description": "document description",
    "tags": ["tag1", "tag2"],
    "supplemental": "partner specific information"
    "creatorIdSD": "b89d898d-c51a-4912-909f-e652b511d023",
    "creatorId": "764ea18872a34337",
    "status": "review",
    "createdDate": 1481014475,
    "hasUnreadSectionChanges": false,
    "hasUnreadConversationChanges": false,
    "hasOpenedDocument": false,
    "archived": false,
    "groupId": "group9"
}

POST /partner/imports/word/upload

Description: Importing Word Documents

Hint

Please find a code example for multipart/form-data uploads here: api_guide.html#importing-word-documents

REQUEST:

URL: https://partner-api.smashdocs.net/partner/imports/word/upload
METHOD: POST
Headers:
    content-type: multipart/form-data
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiNTRhZjI4MTAtMzk1Mi00ZjFmLWE2N2YtODI4OWNiYzE0NGQ0IiwiaWF0IjoxNDc2Mjc0ODMzfQ.1hnj2xqZjDwOvFrLZo5VexA6U7qf4NOZWRAwq7EhzSk

Form Data:
    "file":
         << DOCX - FILE >>
    "data":
         << JSON metadata and user information >>
          {
              "user": {
                 "email": "steven.miller@yourcompany.com",
                 "firstname": "Steven",
                 "lastname": "Miller",
                 "userId": "764ea18872a34337",
                 "company": "yourcompany"
              },
              "title": "my first SMASHDOCs document",
              "description": "",
              "groupId": "85c2602653b7c",
              "userRole": "approver",
              "sectionHistory": true,
              "status": "draft"
          }
RESPONSE:

{
    "documentAccessLink": "https://partner.smashdocs.net/#/document/8e6875cb-5cd2-4178-8ad4-d77b92173bf9
                           &otpt=c938609e2bfc3e8049346a7fef96506aab6babc2e918dd9787a1ae7ce70b3fb1",
    "userIdSD": "b01b8477-01aa-49fe-8cfb-3d3cb00fac1b",
    "documentId": "8e6875cb-5cd2-4178-8ad4-d77b92173bf9"
}

POST /partner/imports/sdxml/upload

Description: Importing XML Documents

Hint

Please find a code example for multipart/form-data uploads here: api_guide.html#importing-xml-documents

ZIP file specification:

- sd.xml (the xml file references the images like "<image [...]>image1.jpg</image>")
+ images (the base dir for images)
   | - image1.jpg
   | - image2.jpeg
   | - image3.png
   | - image4.gif
REQUEST:

URL: https://partner-api.smashdocs.net/partner/imports/sdxml/upload
METHOD: POST
Headers:
    content-type: multipart/form-data
    x-client-id: 60158fa4fcdf3b5b0645b1a5ee2135cdfb6f0bb1bb
    authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI3NjRlYTE4ODcyYTM0MzM3IiwianRpIjoiNTRhZjI4MTAtMzk1Mi00ZjFmLWE2N2YtODI4OWNiYzE0NGQ0IiwiaWF0IjoxNDc2Mjc0ODMzfQ.1hnj2xqZjDwOvFrLZo5VexA6U7qf4NOZWRAwq7EhzSk

Form Data:
    "file":
         << XML Zip - FILE >>
    "data":
         << JSON metadata and user information >>
          {
              "user": {
                 "email": "steven.miller@yourcompany.com",
                 "firstname": "Steven",
                 "lastname": "Miller",
                 "userId": "764ea18872a34337",
                 "company": "yourcompany"
              },
              "title": "my first SMASHDOCs document",
              "description": "",
              "groupId": "85c2602653b7c",
              "userRole": "approver",
              "sectionHistory": true,
              "status": "draft"
          }
RESPONSE:

{
    "documentAccessLink": "https://partner.smashdocs.net/#/document/8e6875cb-5cd2-4178-8ad4-d77b92173bf9
                           &otpt=c938609e2bfc3e8049346a7fef96506aab6babc2e918dd9787a1ae7ce70b3fb1",
    "userIdSD": "b01b8477-01aa-49fe-8cfb-3d3cb00fac1b",
    "documentId": "8e6875cb-5cd2-4178-8ad4-d77b92173bf9"
}