Partner API Documentation¶

Table of Contents

Basics and Principles
API Functions
Examples

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

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 = {} # document creation payload like e.g. POST /partner/documents/create

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#smashdocs-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.

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)

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/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"
}