OfficeDrop and PaperPort Anywhere API

This API is for both OfficeDrop and PaperPort Anywhere - develop for one and get both document management integrations! We are also working our our API License Agreement, and welcome any comments you might have on it.

Marketing Support for Integration Partners

We are committed to helping our developer partners grow their business. This includes using our blog, social media, montly email newsletters and press reach to help make your integration a success. Contact healy (at) officedrop (dot) com to learn more.

Sample Application using the OfficeDrop API

http://github.com/officedrop

OfficeDrop API Calls Document

This document describes the API calls available for applications that want to access an OfficeDrop account.

Contents

OfficeDrop API calls document................................................................................................................ 2

OfficeDrop and Amazon S3..................................................................................................................... 5

Authentication mechanisms.................................................................................................................... 6

HTTP Basic authentication................................................................................................................... 6

OAuth authentication......................................................................................................................... 6

Validating user credentials...................................................................................................................... 9

User Registration.................................................................................................................................. 11

Recovering a lost username.................................................................................................................. 13

Recovering a lost password................................................................................................................... 14

Documents Resource............................................................................................................................ 15

Documents list and search................................................................................................................. 15

View a single document.................................................................................................................... 17

Documents search............................................................................................................................ 18

Opening a document with highlights.................................................................................................. 23

Sample Response.......................................................................................................................... 23

Uploading a document...................................................................................................................... 26

Deleting documents.......................................................................................................................... 28

Undeleting documents...................................................................................................................... 28

View documents in trash................................................................................................................... 29

Purging documents........................................................................................................................... 31

Listing documents without folder (documents at the user’s home folder).......................................... 32

Favorite documents.............................................................................................................................. 35

Marking a single document as a favorite............................................................................................ 35

Listing all favorite documents for a user............................................................................................. 35

Removing a document from your favorites list................................................................................... 37

Marking many documents as favorites............................................................................................... 37

Unfavoriting many documents.......................................................................................................... 38

Getting a list of ids of the documents the user has favorite................................................................ 38

Batches resource.................................................................................................................................. 40

Getting a specific batch..................................................................................................................... 40

Listing batches.................................................................................................................................. 41

Folders Resource.................................................................................................................................. 47

Listing folders.................................................................................................................................... 47

Creating a new folder........................................................................................................................ 48

Updating a folder’s information......................................................................................................... 49

Deleting a folder............................................................................................................................... 49

Moving a document to a folder.......................................................................................................... 49

Move a list of documents to a folder.................................................................................................. 49

Label Resource..................................................................................................................................... 51

List all labels...................................................................................................................................... 51

Create a label.................................................................................................................................... 51

Update a label................................................................................................................................... 52

Delete a label.................................................................................................................................... 52

Delete many labels at the same time................................................................................................. 52

Apply labels for a set of documents................................................................................................... 53

Remove labels from a set of documents............................................................................................ 53

Artifacts................................................................................................................................................ 55

Downloading the document in PDF format......................................................................................... 55

Downloading the original document uploaded to OfficeDrop.............................................................. 55

The page in the “display” format........................................................................................................ 56

The page in the “thumbnail” format................................................................................................... 56

The page in the “snippet_full” format................................................................................................ 56

The page in full resolution................................................................................................................. 57

Sharing a resource................................................................................................................................ 58

Shared documents............................................................................................................................ 59

Shared folders.................................................................................................................................. 61

Glossary............................................................................................................................................... 63

OfficeDrop and Amazon S3

All files and resources that you send to OfficeDrop are processed and then stored at the S3 service at Amazon. For security reasons, theses files are always saved as private objects, there’s no way for an external entity access those files directly.

The only way to let an external party to access one of those files is to give them a signed S3 url for that specific file. Signed S3 URLs have an expiration time set on them, so you can not store them forever as once they expire you will not be able to access the resource again. Throughout this API document you will notice that there are various URLs to download files that point to the OfficeDrop website, these URLs are, in fact, bridges. They will not give you the file stored in S3, they’ll generate a signed URL and will then redirect you to that URL.

So, when calling the OfficeDrop API and trying to download files, be it document images or document files, you must remember to tell your HTTP library to follow the redirect or you will not be able to access the file. Also, you should never cache these signed URLs, as they will expire and you will not be able to access the document anymore, you should always store the bridge URL at your end and never the S3 signed URL.

Imagine that you’re trying to download a full page version of the first page of a document, this is the URL you would call to get it:

https://www.officedrop.com/ze/api/documents/1099/pages/1/display

The response to this request would be a redirect to this URL:

https://s3.amazonaws.com/john-doe-bucket/users/111/batches/1457445924/dsp/00001.d.jpeg?AWSAccessKeyId=AKIAJYQQDPUWKJLGQUBA&Expires=1282508400&Signature=qqh2zKjf1%2BTWN8WlyKCvB2WsmuI%3D

And with this URL you would finally access the page information.

Authentication mechanisms

All calls to the API should be done over HTTPS connections to keep user information protected over connections.

Most of the API calls require the user to be authenticated to the application, this can be done in various ways but they all lead to the same idea, the user must say who he is to the application so we can load the correct information for his account. Right now the supported authentication methods are HTTP Basic Auth and OAuth.

By default, you can expect all calls to require authentication, unless the specific API documentation says that the call doesn’t require it.

All calls that require authentication can use the authentication methods provided below:

HTTP Basic authentication

When using HTTP Basic you just have to send the username and password for the OfficeDrop account at the HTTP Basic headers.

Sample CURL call:

curl -u "johnsmith:123456" https://www.officedrop.com/api/folders.xml

OAuth authentication

Our request token path is at https://www.officedrop.com/oauth/request_token and the access token path is at https://www.officedrop.com/oauth/access_token.

The first step to start using the OfficeDrop API via OAuth is signing up for OfficeDrop (at http://www.officedrop.com/ ) and registering an Application, this is where you get the OAuth consumer token and secret to start making OAuth calls to our service.

After clicking at the “Account” you should click at the OAuth Applications option:

In the next page select “Register Your Application”:

Fill in your application details:

And at the final step you’ll see the OAuth token and secret values:

Validating user credentials

URL: https://{server_host}/ze/api/session.xml

Method: POST

Parameters:

If HTTP Basic authentication is going to be used:

username - string - the user’s username at OfficeDrop
password - string - the user’s password at OfficeDrop

This call does not require authentication.

Sample curl request:

curl -v -d "username=johnsmith&password=123456" https://www.officedrop.com/ze/api/session.xml

Success response:

<?xml version="1.0" encoding="UTF-8"?>

<user>

<customer-name>John Smith</customer-name>

<email>johnsmith@mail.com</email>

<username>johnsmith</username>

<domain-prefix>johnsmith-account</domain-prefix>

<name>John Smith Account</name>

</account>

</accounts>

</user>

Error response:

<?xml version="1.0" encoding="UTF-8"?>

<message>Incorrect username or password </message>

<status>error</status>

</message>

A success response for this request assures the caller that the user with the credentials provided exists and has an account (or more than one) enabled on OfficeDrop.

User Registration

URL: https://{server_host}/ze/api/users.xml

Method: POST

Parameters:

“user[username]” - the username that’s going to be used at OfficeDrop
“user[password]” - the password that’s going to be used
“user[custumer_name]” - the customer name that the user will be called at the OfficeDrop application
“user[email]” - the user’s email address

Sample CURL call:

curl -d "user[username]=john&user[customer_name]=john&user[password]=12345678&user[email]=john@mail.com" https://www.officedro.com/ze/api/users.xml

Sample success response:

<?xml version="1.0" encoding="UTF-8"?>

<user>

<customer-name>John Smith</customer-name>

<email>johnsmith@mail.com</email>

<username>johnsmith</username>

</user>

Sample error response:

<?xml version="1.0" encoding="UTF-8"?>

<![CDATA[can't be blank]]>

</error>

<![CDATA[can't be blank]]>

</error>

<![CDATA[should be 4 characters or more]]>

</error>

<![CDATA[should include only letters, numbers and underscores (minimum size: 3 characters)]]>

</error>

<![CDATA[can't be blank]]>

</error>

<![CDATA[can't be blank]]>

</error>

</errors>

Recovering a lost username

URL: https://{server_host}/ze/api/reminder/username.xml

Parameters:

“email” - required - the user’s email tied to his account at OfficeDrop

Sample curl call:

curl -d "email=johnsmith@mail.com" https://www.officedrop.com/ze/api/reminder/username.xml

Sample success response:

<?xml version="1.0" encoding="UTF-8"?>

<message>Your username has been emailed to you.</message>

<status>success</status>

</message>

Sample error response:

<?xml version="1.0" encoding="UTF-8"?>

<message>The details provided were not correct. Please try again.</message>

<status>error</status>

</message>

Recovering a lost password

URL: https://{server_host}/api/reminder/password.xml

Parameters:

“email” - required - the user’s email tied to his account at OfficeDrop
“username” - required - the user’s username at OfficeDrop

Sample curl call:

curl -d "email=johnsmith&username=johnsmith" https://www.officedrop.com/api/reminder/password.xml

Sample success response:

<?xml version="1.0" encoding="UTF-8"?>

<message> Instructions on how to continue to reset your password have been sent to your email address.</message>

<status>success</status>

</message>

Sample error response:

<?xml version="1.0" encoding="UTF-8"?>

<message>The details provided were not correct. Please try again.</message>

<status>error</status>

</message>

Documents Resource

Documents list and search

This is the call you will do to show documents to the user and also to search for documents or filter them using folder, label or favorites information.

URL: https://{server_host}/ze/api/documents.xml

Method: GET

Parameters:

q - string - the keywords that are going to be searched for
page - integer - the page of the documents listing you’d like to receive (not required, defaults to 1)
per_page - integer - how many documents you’d like to see on every results page (not required, defaults to 15)
folder_id - integer - the id of the folder you would like to use to filter the documents (ex. “&folder_id=4”)
label_ids - integer - a list of label ids separated by commas (“,”) to use to filter the documents (ex. “&label_ids=2,5,90,54”)
favorites - string - either “true” or blank, show only documents that are in the filters above and are marked as favorites by the user (ex. “&favorites=true”)
sort - string - the sorting order that should be used to return documents (not required - defaults to newest first)
- newest - newest documents first
- oldest - older documents first
- most_viewed - most viewed first
- name - by name ascending
- name_reverse - by name, descending
- recently_viewed - by the last time the document was saw
- most_viewed - by the quantity of times the document was viewed
- relevance - by the relevance of the document based on the search results

Sample curl request:

curl -v -u "johnsmith:123456" https://www.officedrop.com/ze/api/documents.xml?page=1&per_page=5

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<current-page>1</current-page>

<per-page>15</per-page>

<total-entries>2</total-entries>

<total-pages>1</total-pages>

</pagination>

<cover>https://www.officedrop.com/ze/api/documents/1159/cover</cover>

<download>https://www.officedrop.com/ze/api/documents/1159/download</download>

<name>OfficePad_Prioritized_Wishlist.pdf</name>

<page-count>1</page-count>

<label>

<name>api testing</name>

</label>

</labels>

<name>Default</name>

<parent-folder>

</parent-folder>

</folder>

</document>

<cover>https://www.officedrop.com/ze/api/documents/1153/cover</cover> <download>https://www.officedrop.com/ze/api/documents/1153/download</download>

<name>Draft for newcomers.pdf</name>

<page-count>7</page-count>

<label>

<name>api testing</name>

</label>

</labels>

<name>Default</name>

<parent-folder>

</parent-folder>

</folder>

</document>

</documents>

This response represents the document basic information, the fields cover and download are bridge URLs that will redirect the requestor to an signed Amazon S3 URL where the document really lives, so, the HTTP library that requests this URL should be able to follow HTTP redirect responses (307 HTTP code). Check the beginning of the document for a full explanation on bridge URLs and S3.

The documents are always returned using pagination and the pagination data is also part of the XML response so client applications can show the user pagination widgets when listing documents.

View a single document

URL: https://{server_host}/ze/api/documents/[document_id].xml

Method: GET

Sample curl request:

curl -v -u "johnsmith:123456" https://www.officedrop.com/ze/api/documents/1024.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<batch-type>UPLOAD</batch-type>

<cover>https://www.officedrop.com/ze/api/documents/1159/cover</cover>

<created-at>2010-02-27T15:18:01Z</created-at>

<download>https://www.officedrop.com/ze/api/documents/1159/download</download>

<name>OfficePad_Prioritized_Wishlist.pdf</name>

<page-count>1</page-count>

<updated-at>2010-02-27T15:18:31Z</updated-at>

<view-count>0</view-count>

<label>

<name>api testing</name>

</label>

</labels>

</document>

Documents search

URL: https://{server_host}/ze/api/documents/search.xml

Method: GET

Parameters:

q - string - the keywords that are going to be searched for
page - integer - the page of the documents listing you’d like to receive (not required, defaults to 1)
per_page - integer - how many documents you’d like to see on every results page (not required, defaults to 15)
folder_id - integer - the id of the folder you would like to use to filter the documents
label_ids - integer - a list of label ids separated by commas (“,”) to use to filter the documents
sort - string - the sorting order that should be used to return documents (not required - defaults to newest first)
- newest - newest documents first
- oldest - older documents first
- most_viewed - most viewed first
- name - by name ascending
- name_reverse - by name, descending
- recently_viewed - by the last time the document was saw
- most_viewed - by the quantity of times the document was viewed
- relevance - by the relevance of the document based on the search results

Sample curl request:

curl -v -u "user111:password" --basic localhost:3000/api/documents/search.xml?page=1&per_page=5&q=pixily&label_ids=12,45,95&folder_id=4

Sample response:

<current-page>1</current-page>

<per-page>3</per-page>

<total-entries>1</total-entries>

<total-pages>1</total-pages>

</pagination>

<batch-type>UPLOAD</batch-type>

<created-at>2010-03-18T12:05:04Z</created-at>

<download>http://localhost:3000/ze/api/documents/1086/download</download>

<name>rsync.pdf</name>

<page-count>6</page-count>

<status>READY_FOR_USER</status>

<updated-at>2010-03-18T12:05:29Z</updated-at>

<view-count>0</view-count>

<label>

<name>api testing</name>

</label>

</labels>

<parent-folder>

</parent-folder>

</folder>

<page-hits>

<page-hit>

<display>http://localhost:3000/ze/api/documents/1086/page/1/display</display>

<thumbnail>http://localhost:3000/ze/api/documents/1086/page/1/thumbnail</thumbnail>

</rectangles>

</page-hit>

</page-hits>

</document>

</documents>

Response details.

/documents/document/page-hits/page-hit: each <page-hit> object contains information about the terms found in a single page, you can use this information to show the page with highlights at the positions defined in the <rectangles> definition.

/documents/document/page-hits: a set of page-hit , for this first search just one per page will show up

/documents/document/page-hits/page-hit/number: page number

/documents/document/page-hits/page-hit/fetch: URL to get the document with word geometries.

/documents/document/page-hits/page-hit/thumbnail: thumbnail page of <number/>

/documents/document/page-hits/page-hit/display: display page of <number/> to position <rectangles/>

/documents/document/page-hits/page-hit/size: page size (width/sizeX)x(height/sizeY)

/documents/document/page-hits/page-hit/rectangles: set of rectangles to highlight each word.

Highlight positioning

Opening a document with highlights

This call is meant to be done after you performed a search and now you want to show the document highlighting the places where the words searched show up on it. As you get images of the pages when viewing them, you need the coordinates at the <page-hit> object to be able to highlight these positions at the image, opening a document with highlights will give you a document with all the <page-hit> information.

URL: http://{server_host}/ze/api/documents/{document id}/fetch.xml

Method: GET

Parameters:

q - string - the keywords that are going to be searched for (required)

The server will keep the last search result documents in cache so the fetch action will get the document with highlights.

Sample curl request:

curl -v -u "user111:password" --basic localhost:3000/ze/api/documents/1155/fetch.xml?q=foo

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<batch-type>UPLOAD</batch-type>

<created-at>2010-03-18T12:05:04Z</created-at>

<download>http://localhost:3000/ze/api/documents/1086/download</download>

<name>rsync.pdf</name>

<page-count>6</page-count>

<status>READY_FOR_USER</status>

<updated-at>2010-03-18T12:05:29Z</updated-at>

<view-count>0</view-count>

<parent-folder>

</parent-folder>

</folder>

<page-hits>

<page-hit>

<display>http://localhost:3000/ze/api/documents/1086/page/1/display</display>

<thumbnail>http://localhost:3000/ze/api/documents/1086/page/1/thumbnail</thumbnail>

</rectangles>

</page-hit>

<page-hit>

<display>http://localhost:3000/ze/api/documents/1086/page/2/display</display>

<thumbnail>http://localhost:3000/ze/api/documents/1086/page/2/thumbnail</thumbnail>

</rectangles>

</page-hit>

<page-hit>

<display>http://localhost:3000/ze/api/documents/1086/page/4/display</display>

<thumbnail>http://localhost:3000/ze/api/documents/1086/page/4/thumbnail</thumbnail>

</rectangles>

</page-hit>

<page-hit>

<display>http://localhost:3000/ze/api/documents/1086/page/5/display</display>

<thumbnail>http://localhost:3000/ze/api/documents/1086/page/5/thumbnail</thumbnail>

</rectangles>

</page-hit>

<page-hit>

<display>http://localhost:3000/ze/api/documents/1086/page/6/display</display>

<thumbnail>http://localhost:3000/ze/api/documents/1086/page/6/thumbnail</thumbnail>

</rectangles>

</page-hit>

</page-hits>

</document>

Uploading a document

URL: https://{server_host}/ze/api/documents.xml

Method: POST

Parameters:

uploaded_data - mutipart attachment - the file that’s being uploaded formatted as a multipart attachment
folder_id - integer - the folder to which the document should be sent to, defaults to no folder (or root folder)
labels - string - list of labels to be applied to this document, separated by commas

When making this call remember to format all fields as multipart attachments and change the request content type to “multipart/form-data”.

Sample curl request:

curl -v -u "johnsmith:123456" -F "uploaded_data=@/home/johnsmith/pixily-test-18.pdf;type=application/pdf" -F "folder_id=4" https://www.officedro.com/ze/api/documents.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<batch>

<batch-status>RECEIVED</batch-status>

<batch-type>UPLOAD</batch-type>

<content-type>application/pdf</content-type>

<extract-type>text</extract-type>

<name>pixily-test-18.pdf</name>

<name>Default</name>

<parent-folder>

</parent-folder>

</folder>

<user>

<customer-name>John Smith</customer-name>

<email>johnsmith@mail.com</email>

<username>johnsmith</username>

</user>

</batch>

When a document is uploaded, you will not receive a document object back from the controller but a <batch/> object that represents the future document. A batch represents that the document is being prepared for processing, once the batch reaches the READY_FOR_USER state (on the <batch-status/> attribute) the document is ready to be used (and the batch will point to it).

A client application can keep on requesting the information about the batch (using the batch id) to figure out if the document is ready (or if the batch failed). If the batch is failed with the following statuses CANCELLED, ABANDONED, DUPLICATE, it cannot be retried again. You can get more information about batches and their statuses on the Batches section of this document.

Deleting documents

URL: https://{server_host}/ze/api/documents/delete.xml

Method: POST

Authentication required: Yes

Parameters:

“document_ids”: the ids of the documents that should be moved to the trash separated by commas (“,”);

This call marks a document as deleted and moves it to the trash, this call doesn’t delete the document forever, there’s another call, “purge”, that will do that. This document will not be available again at the general documents listing call, it will only show up at the trashed documents listing.

Sample curl call:

curl -v -u "johnsmith:123456" -d “document_ids=1149,1150” https://www.officedrop.com/ze/api/documents/delete.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<message>Documents successfully moved to the trash</message>

<status>success</status>

</message>

Undeleting documents

URL: https://{server_host}/ze/api/documents/undelete.xml

Method: POST

Authentication required: Yes

Parameters:

“document_ids”: the ids of the documents that will be undeleted separated by commas (“,”);

This call will “undelete” a document (ie. get a deleted document and move it out of the trashed documents listing). After being undeleted the document will show up again on the main documents listing calls.

Sample curl call:

curl -v -u "johnsmith:123456" -d “document_ids=1159,1160” https://www.officedrop.com/ze/api/documents/undelete.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<message>Documents successfully moved out of the trash</message>

<status>success</status>

</message>

View documents in trash

URL: https://{server_host}/ze/api/documents/trashed.xml

Method: GET

Authentication required: Yes

This call returns all documents that were marked as “deleted” by the application (documents that received a “delete” call). This is the only place you can view deleted documents.

Sample curl call:

curl -v -u "johnsmith:123456" https://www.officedrop.com/ze/api/documents/trashed.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<current-page>1</current-page>

<per-page>15</per-page>

<total-entries>2</total-entries>

<total-pages>1</total-pages>

</pagination>

<batch-type>UPLOAD</batch-type>

<created-at>2010-02-27T15:10:36Z</created-at>

<download>https://www.officedrop.com/ze/api/documents/1149/download</download>

<name>pixily-test-11.pdf</name>

<page-count>1</page-count>

<status>DELETED</status>

<updated-at>2010-04-08T15:07:16Z</updated-at>

<view-count>0</view-count>

<name>Default</name>

<parent-folder>

</parent-folder>

</folder>

<page-hits/>

</document>

<batch-type>UPLOAD</batch-type>

<created-at>2010-02-27T15:18:01Z</created-at>

<download>https://www.officedrop.com/ze/api/documents/1159/download</download>

<name>OfficePad_Prioritized_Wishlist.pdf</name>

<page-count>1</page-count>

<status>DELETED</status>

<updated-at>2010-03-05T19:45:26Z</updated-at>

<view-count>1</view-count>

<label>

<name>api testing</name>

</label>

</labels>

<name>Default</name>

<parent-folder>

</parent-folder>

</folder>

<page-hits/>

</document>

</documents>

Purging documents

URL: https://{server_host}/ze/api/documents/purge.xml

Method: POST

Authentication required: Yes

Parameters:

“document_ids”: the ids of the documents that will be permanently deleted separated by commas (“,”);

This call will permanently delete the document from the OfficeDrop service, there is no way to undo this action, so please use this carefully.

Sample curl call:

curl -v -u "johnsmith:123456" -d “document_ids=1159,1160” https://www.officedrop.com/ze/api/documents/purge.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<message> Documents were permanently deleted from our service</message>

<status>success</status>

</message>

Listing documents without folder (documents at the user’s home folder)

URL: https://{server_host}/ze/api/documents/home.xml

Method: GET

Authentication required: Yes

Parameters:

q - string - the keywords that are going to be searched for (not required)
page - integer - the page of the documents listing you’d like to receive (not required, defaults to 1)
per_page - integer - how many documents you’d like to see on every results page (not required, defaults to 15)
label_ids - integer - a list of label ids separated by commas (“,”) to use to filter the documents (not required)
sort - string - the sorting order that should be used to return documents (not required - defaults to newest first)
- newest - newest documents first
- oldest - older documents first
- most_viewed - most viewed first
- name - by name ascending
- name_reverse - by name, descending
- recently_viewed - by the last time the document was saw
- most_viewed - by the quantity of times the document was viewed
- relevance - by the relevance of the document based on the search results

When a document is uploaded and no folder is defined, this document goes to the user’s Home folder, that is a folder only that specific user can view. Only documents explicitly uploaded to public folders will be visible to other users.

Sample curl call:

curl -u "johnsmith:123456" https://www.officedrop.com/ze/api/documents/home.xml

Sample output:

<?xml version="1.0" encoding="UTF-8"?>

<current-page>1</current-page>

<per-page>15</per-page>

<total-entries>1</total-entries>

<total-pages>1</total-pages>

</pagination>

<batch-type>UPLOAD</batch-type>

<cover>https://www.officedrop.com/ze/api/documents/1157/cover</cover>

<created-at>2010-02-27T15:17:20Z</created-at>

<download>https://www.officedrop.com/ze/api/documents/1157/download</download>

<name>pixily-sample.pdf</name>

<original>https://www.officedrop.com/ze/api/documents/1157/original</original>

<page-count>1</page-count>

<status>READY_FOR_USER</status>

<updated-at>2010-04-12T20:10:25Z</updated-at>

<view-count>18</view-count>

<parent-folder>

</parent-folder>

</folder>

<page-hits/>

<label>

<name>api testing</name>

</label>

<label>

<name>Receipt</name>

</label>

<label>

</label>

<label>

<name>Utility</name>

</label>

</labels>

</document>

</documents>

Favorite documents

These calls will allow you to mark a document as a favorite for a user and also list all documents marked as favorites for that user.

Marking a single document as a favorite

URL: https://{server_host}/ze/api/document_favorites.xml

Method: POST

Parameters:

id - the “id” of the document you want favorite

Sample curl call:

curl -u "johnsmith:123456" -d "id=1149" https://www.officedrop.com/ze/api/document_favorites.xml

Sample success response:

<?xml version="1.0" encoding="UTF-8"?>

<message>The document was successfully added to your favorites list</message>

<status>success</status>

</message>

Listing all favorite documents for a user

URL: https://{server_host}/ze/api/document_favorites.xml

Method: GET

Parameters:

q - string - the keywords that are going to be searched for (not required)
page - integer - the page of the documents listing you’d like to receive (not required, defaults to 1)
per_page - integer - how many documents you’d like to see on every results page (not required, defaults to 15)
folder_id - integer - the id of the folder you would like to use to filter the documents (not required)
label_ids - integer - a list of label ids separated by commas (“,”) to use to filter the documents (not required)
sort - string - the sorting order that should be used to return documents (not required - defaults to newest first)
- newest - newest documents first
- oldest - older documents first
- most_viewed - most viewed first
- name - by name ascending
- name_reverse - by name, descending
- recently_viewed - by the last time the document was saw
- most_viewed - by the quantity of times the document was viewed
- relevance - by the relevance of the document based on the search results

Sample curl call:

curl --basic -u "johnsmith:123456" https://www.officedrop.com/ze/api/document_favorites.xml

Sample success response:

<?xml version="1.0" encoding="UTF-8"?>

<current-page>1</current-page>

<per-page>15</per-page>

<total-entries>1</total-entries>

<total-pages>1</total-pages>

</pagination>

<original>https://www.officedrop.com/ze/api/documents/1149/original</original>

<download>https://www.officedrop.com/ze/api/documents/1149/download</download>

<cover>https://www.officedrop.com/ze/api/documents/1157/cover</cover>

<batch-type>UPLOAD</batch-type>

<created-at>2010-02-27T15:10:36Z</created-at>

<name>pixily-test-11.pdf</name>

<page-count>1</page-count>

<status>READY_FOR_USER</status>

<updated-at>2010-02-27T15:10:46Z</updated-at>

<view-count>0</view-count>

<name>Default</name>

</folder>

</document>

</documents>

Removing a document from your favorites list

URL: https://{server_host}/ze/api/document_favorite

Marking many documents as favorites

URL: https://{server_host}/ze/api/document_favorites/favorite.xml

Method: POST

Parameters:

“document_ids” : list of document ids to favorite separated by commas (“,”)

Sample curl call:

curl -u "johnsmith:123456" -d "document_ids=1151,1153" https://www.officedro.com/ze/api/document_favorites/favorite.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<message>The documents were successfully added to your favorites list</message>

<status>success</status>

</message>

Unfavoriting many documents

URL: https://{server_host}/ze/api/document_favorites/unfavorite.xml

Method: POST

Parameters:

“document_ids” : list of document ids to unfavorite separated by commas (“,”)

Sample curl call:

curl -u "johnsmith:123456" -d "document_ids=1151,1153" https://www.officedrop.com/ze/api/document_favorites/unfavorite.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<message>The documents were successfully removed from your favorites list</message>

<status>success</status>

</message>

Getting a list of ids of the documents the user has favorite

Purpose: The purpose of this call is to load and cache all documents that are already marked as favorites for the current user so the application can show a sign that a document is favorited without making a call for every document.

URL: https://{server_host}/ze/api/document_favorites/ids.xml

Method: GET

Sample CURL call:

curl -u "johnsmith:123456" https://www.officedrop.com/ze/api/document_favorites/ids.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

</document>

</document>

</documents>

Batches resource

Right when you upload a file to create a document at our service you don’t receive a document back, you receive a <batch/> object that will tell you at which state that specific file is. Before building the real document, OfficeDrop needs to convert it into a format we can extract text from it, we then index the extracted text, build a PDF version of the document and we finally sum up all these files to build the document representation you see at our website and at the API.

You could use the calls to the batch resource to let the user know at which state the document it just uploaded is and tell the user when the document itself is ready.

Getting a specific batch

URL: https://{server_host}/ze/api/batches/[batch_id].xml

Method: GET

Sample curl request:

curl -v -u "johnsmith:123456" https://www.officedrop.com/ze/api/batches/1457445964.xml

Sample request:

<?xml version="1.0" encoding="UTF-8"?>

<batch>

<batch-status>READY_FOR_USER</batch-status>

<batch-type>UPLOAD</batch-type>

<content-type>application/pdf</content-type>

<extract-type>text</extract-type>

<name>pixily-test-11.pdf</name>

<batch-type>UPLOAD</batch-type>

<created-at>2010-02-27T15:10:36Z</created-at>

<name>pixily-test-11.pdf</name>

<page-count>1</page-count>

<status>READY_FOR_USER</status>

<updated-at>2010-02-27T15:10:46Z</updated-at>

<view-count>0</view-count>

<name>Default</name>

</folder>

</document>

</documents>

<name>Default</name>

</folder>

<user>

<customer-name>John Smith</customer-name>

<email>johnsmith@mail.com</email>

<username>johnsmith</username>

</user>

</batch>

Listing batches

URL: https://{server_host}/ze/api/batches.xml

Method: GET

Parameters:

page - integer - the page of batches you’d like to receive (not required, defaults to 1)
per_page - integer - the number of items per page (not required, defaults to 1)
status - string - the status of the batches you’d like to receive, there are 3 possible values for this parameter (not required, defaults to select all batches and not filter at all):

o started

o failed

o completed

Sample curl request:

curl -v -u "johnsmith:123456" https://www.officedrop.com/ze/api/batches.xml?status=completed

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<current-page>1</current-page>

<per-page>15</per-page>

<total-entries>4</total-entries>

<total-pages>1</total-pages>

</pagination>

<batch>

<batch-status>READY_FOR_USER</batch-status>

<batch-type>UPLOAD</batch-type>

<content-type>application/pdf</content-type>

<extract-type>text</extract-type>

<name>folder-to-notebook-link.pdf</name>

<batch-type>UPLOAD</batch-type>

<created-at>2010-02-27T15:17:01Z</created-at>

<name>folder-to-notebook-link.pdf</name>

<page-count>2</page-count>

<status>READY_FOR_USER</status>

<updated-at>2010-02-27T15:17:48Z</updated-at>

<view-count>0</view-count>

<name>Default</name>

</folder>

</document>

</documents>

<name>Default</name>

</folder>

<user>

<customer-name>John Smith</customer-name>

<email>johnsmith@mail.com</email>

<username>johnsmith</username>

</user>

</batch>

<batch>

<batch-status>READY_FOR_USER</batch-status>

<batch-type>UPLOAD</batch-type>

<content-type>application/pdf</content-type>

<extract-type>text</extract-type>

<name>pixily-sample.pdf</name>

<batch-type>UPLOAD</batch-type>

<created-at>2010-02-27T15:17:20Z</created-at>

<name>pixily-sample.pdf</name>

<page-count>1</page-count>

<status>READY_FOR_USER</status>

<updated-at>2010-03-01T19:15:59Z</updated-at>

<view-count>1</view-count>

<name>Default</name>

</folder>

</document>

</documents>

<name>Default</name>

</folder>

<user>

<customer-name>John Smith</customer-name>

<email>johnsmith@mail.com</email>

<username>johnsmith</username>

</user>

</batch>

<batch>

<batch-status>READY_FOR_USER</batch-status>

<batch-type>UPLOAD</batch-type>

<content-type>application/pdf</content-type>

<extract-type>text</extract-type>

<name>pixily-test-11.pdf</name>

<batch-type>UPLOAD</batch-type>

<created-at>2010-02-27T15:10:36Z</created-at>

<name>pixily-test-11.pdf</name>

<page-count>1</page-count>

<status>READY_FOR_USER</status>

<updated-at>2010-02-27T15:10:46Z</updated-at>

<view-count>0</view-count>

<name>Default</name>

</folder>

</document>

</documents>

<name>Default</name>

</folder>

<user>

<customer-name>John Smith</customer-name>

<email>johnsmith@mail.com</email>

<username>johnsmith</username>

</user>

</batch>

</batches>

Folders Resource

Listing folders

URL: https://{server_host}/ze/api/folders.xml

Method: GET

Action: List all folders from a user.

Sample curl request:

curl -v -u "johnsmith:123456" https://www.officedrop.com/ze/api/folders.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<folder-type>home</folder-type>

</folder>

<folder-type>regular</folder-type>

<name>google docs folder</name>

<child-folders>

<child-folder>

<folder-type>regular</folder-type>

<name>Internal folder</name>

</child-folder>

</child-folders>

</folder>

<folder-type>regular</folder-type>

<child-folders>

<child-folder>

<folder-type>regular</folder-type>

<name>internal1</name>

<child-folders>

<child-folder>

<folder-type>regular</folder-type>

<name>internal2</name>

</child-folder>

</child-folders>

</child-folder>

</child-folders>

</folder>

</folders>

Creating a new folder

URL: https://{server_host}/ze/api/folders.xml

Method: POST

Action: Create folder.

Parameters:

name - string – New folder name
parent_id – integer – parent folder id (optional)

Sample curl request:

curl -v -X POST -u “johnsmith:123456” -d "name=foldername&parent_id=2" https://www.officedrop.com/ze/api/folders.xml

Response: List all folders from a user updated.

Updating a folder’s information

URL: https://{server_host}/ze/api/folders/{folder id}.xml

Method: PUT

Action: Updating a folder (renaming it).

Sample curl request:

curl -v -X PUT -u “johnsmith:123456” -d "name=nice documents" https://www.officedrop.com/ze/api/folders/4.xml

Response: List all folders from a user updated.

Deleting a folder

URL: http://{server_host}/ze/api/folders/{folder id}.xml

Method: DELETE

Action: Delete a folder

Sample curl request:

curl -v -X DELETE -u “johnsmith:123456” https://www.officedrop.com/ze/api/folders/3.xml

Response: List all updated folders.

This call doesn’t really delete a folder and it’s contents, it just sends them all to the trash, you can view which folders are trashed at the trashed folders call.

Moving a document to a folder

URL: https://{server_host}/ze/api/folders/{folder id}/moveto.xml

Method: POST

Action: Move a document to folder

Parameters:

document - integer – Document id

Sample curl request:

curl -v -X POST -d "document=333" -u “johnsmith:123456” https://www.officedrop.com/ze/api/folders/2/moveto.xml

Response: List all updated folders.

Move a list of documents to a folder

URL: https://{server_host}/ze/api/folders/{folder id}/moveto.xml

Method: POST

Action: Move a list of documents to folder

Parameters:

documents[] - integer – Document id

Sample curl request:

curl -v -X POST -d "documents[]=333&documents[]=4444" -u “johnsmith:123456” https://www.officedrop.com/ze/api/folders/2/moveto.xml

The request above will move the documents 333 and 4444 to folder id 2

Response: List all updated folders.

Label Resource

List all labels

URL: https://{server_host}/ze/api/labels.xml

Method: GET

Action: List all labels.

Sample curl request:

curl -v -u “johnsmith:123456” https://www.officedrop.com/ze/api/labels.xml

XML Response

<?xml version="1.0" encoding="UTF-8"?>

<label>

</label>

<label>

<name>Receipt</name>

</label>

<label>

<name>Utility</name>

</label>

</labels>

Create a label

URL: https://{server_host}/ze/api/labels.xml

Method: POST

Action: Create label.

Parameters:

name - string – Label name

Sample curl request:

curl -v -d "name=labelname" -u “johnsmith:123456” https://www.officedrop.com/ze/api/labels.xml

Response: List all labels.

Update a label

URL: https://{server_host}/ze/api/labels/{label id}.xml

Method: PUT

Action: Update label (renaming).

Parameters:

name - string – New label name.

Sample curl request:

curl -v -X PUT -d "name=labelname" -u “johnsmith:123456” https://www.officedrop.com/ze/api/labels/5.xml

Response: List all labels.

Delete a label

URL: https://{server_host}/ze/api/labels/{label id}.xml

Method: DELETE

Action: Delete label.

Sample curl request:

curl -v -X DELETE -u “johnsmith:123456” https://www.officedrop.com/ze/api/labels/5.xml

Response: List all labels.

Delete many labels at the same time

URL: https://{server_host}/ze/api/labels/destroy_all.xml

Method: DELETE

Parameters:

“label_ids” - list of label IDs separated by commas (“,”)

Sample curl request:

curl -X DELETE -u "johnsmith:123456" -d "label_ids=1,2,5,4" https://www.officedrop.com/ze/api/labels/destroy_all.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<message>Labels successfully removed</message>

<status>success</status>

</message>

Apply labels for a set of documents

URL: https://{server_host}/ze/api/labels/apply.xml

Method: POST

Action: Apply labels for a set of documents

Parameters:

documents[] - integer – Document id.
labels[] – integer – label id

Sample curl request:

curl -v -u “johnsmith:123456” -d "documents[]=333&documents[]=4444&labels[]=777&labels[]=888" https://www.officedrop.com/ze/api/labels/apply.xml"

The labels 777 and 888 will be applied to documents 333 and 444

Response: List all labels.

Remove labels from a set of documents

URL: https://{server_host}/ze/api/labels/apply.xml

Method: POST

Action: Remove labels from a set of documents

Parameters:

documents[] - integer – Document id.
labels[] – integer – label id

Parameters:

“share[shared_type]” - required - the kind of resource that is being shared, valid values are “Folder” or “Document”
“share[shared_id]” - required - the id of the resource that is going to be shared
“share[visibility]” - if the share will be visible for anyone or only for those to whom the email was sent, valid values are “public” or “private”, defaults to “public”
“share[recipients]” - required - list of email addresses separated by commas that will receive the share email
“share[subject]” - the subject that should be used on the email sent to the recipients, defaults to “#{user_name} has shared a document from OfficeDrop".
“share[body]” - the message that will appear at the body of the share email
“share[days]” - the number of days the resource will be shared (only usable if the share is “private”)
“share[cc]” - either “0” or “1” - if you should also receive a copy of the email sent to the recipients
“share[downloadable]” - either “0” or “1” - if the document can be downloaded - (only usable if the share is “private”)
“share[annotations_enabled]” - either “0” or “1” - if the document can be annotated - (only usable if the share is “private”)
“share[no_email]” - either “1” or blank (don’t send it) - if given and true the “share[recipients]” parameter will be ignored and no email will be sent. This parameter can only be used for public shares;

Sample curl call:

curl -u "johnsmith:123456" --basic -d "share[visibility]=public&share[shared_id]=1161&share[shared_type]=Document&share[recipients]=someone@mail.com" https://www.officedrop.com/ze/api/shares.xml

Sample response:

<?xml version="1.0" encoding="UTF-8"?>

<message>The Document selected was successfully shared with the recipients provided</message>

<status>success</status>

</message>

Shared documents

When you share a document, with either a private or a public share, those shares are added to the given document, as in the example below:

<batch-type>UPLOAD</batch-type>

<created-at>2010-07-15T19:36:12Z</created-at>

<download>https://www.officedrop.com/ze/api/documents/1104/download</download>

<name>pixily-test-02 (1).pdf</name>

<original>https://www.officedrop.com/ze/api/documents/1104/original</original>

<page-count>1</page-count>

<status>READY_FOR_USER</status>

<updated-at>2010-07-27T17:47:02Z</updated-at>

<view-count>1</view-count>

<folder-type>home</folder-type>

<name>Items not in folder</name>

<folder-type>regular</folder-type>

</folder>

<page-hits/>

<public-share>

<token>a6d17af1dc4de7956aa4ea1bd3988acaafaab805</token>

<url>https://www.officedrop.com/ze/guest/public/a6d17af1dc4de7956aa4ea1bd3988acaafaab805</url>

<viewed-count>0</viewed-count>

</public-share>

<private-shares>

<private-share>

<access-key>c667d53acd899a97a85de0c201ba99be</access-key>

<annotations-enabled>false</annotations-enabled>

<downloadable>false</downloadable>

<email>friend@mail.com</email>

<expire-at>2284-05-04T23:59:59Z</expire-at>

<shared-at>2010-07-21T11:04:23Z</shared-at>

<status>ACTIVE</status>

<url>https://www.officedrop.com/ze/guest/access/c667d53acd899a97a85de0c201ba99be</url>

<viewed-count>0</viewed-count>

</private-share>

</private-shares>

<cover>

<snippet_full>https://www.officedrop.com/ze/api/documents/1104/pages/1/snippet_full</snippet_full>

<thumbnail>https://www.officedrop.com/ze/api/documents/1104/pages/1/thumbnail</thumbnail>

<display>https://www.officedrop.com/ze/api/documents/1104/pages/1/display</display>

</cover>

</document>

Shared folders

As with documents, when you share a folder, the sharing information becomes part of the folder markup:

<folder-type>regular</folder-type>

<name>google docs folder</name>

<public-share>

<url>https://www.officedrop.com/ze/guest/public/b106fe2ba60efcf7a0d026f12327db931dc25ff8</url>

<viewed-count>0</viewed-count>

<widget-enabled>false</widget-enabled>

</public-share>

<private-shares>

<private-share>

<access-key>c9f95a0a5af052bffce5c89917335f67</access-key>

<annotations-enabled>false</annotations-enabled>

<email>another_friend@mail.com</email>

<expire-at>2010-08-11T23:59:59Z</expire-at>

<shared-at>2010-07-28T15:12:59Z</shared-at>

<status>ACTIVE</status>

<url>https://www.officedrop.com/ze/guest/access/c9f95a0a5af052bffce5c89917335f67</url>

<viewed-count>0</viewed-count>

</private-share>

</private-shares>

</folder>

Glossary

Batch – object that represents a file that was uploaded to OfficeDrop. A batch is the raw material to build a searchable document in our service. Every document is the result of processing a batch.
Document – it’s the result of processing a batch. It contains all pages from the uploaded document and it can be moved to folders, have labels applied to it, shared with other people and more.
Page – a page in the document, usually received as an image.
Page Hit – shows, inside a page in a document, where a word that is a search parameter shows up on that specific page, using Pixel coordinates.
Signed URL – a URL to a resource at S3 that is private. The signature in the URL allows someone that has that URL to access the resource for a limited amount of time. Signed URLs always expire after some time. At the OfficeDrop application they usually expire after 10 minutes of being generated.

Security

Scanning Software

Tour

Pricing

OfficeDrop's Document Management API

OfficeDrop and PaperPort Anywhere API

Marketing Support for Integration Partners

Sample Application using the OfficeDrop API

OfficeDrop API Calls Document

OfficeDrop and Amazon S3

Authentication mechanisms

HTTP Basic authentication

OAuth authentication

Validating user credentials

User Registration

Recovering a lost username

Recovering a lost password

Documents Resource

Documents list and search

View a single document

Documents search

Opening a document with highlights

Sample Response

Uploading a document

Deleting documents

Undeleting documents

View documents in trash

Purging documents

Listing documents without folder (documents at the user’s home folder)

Favorite documents

Marking a single document as a favorite

Listing all favorite documents for a user

Removing a document from your favorites list

Marking many documents as favorites

Unfavoriting many documents

Getting a list of ids of the documents the user has favorite

Batches resource

Getting a specific batch

Listing batches

Folders Resource

Listing folders

Creating a new folder

Updating a folder’s information

Deleting a folder

Moving a document to a folder

Move a list of documents to a folder

Label Resource

List all labels

Create a label

Update a label

Delete a label

Delete many labels at the same time

Apply labels for a set of documents

Remove labels from a set of documents

Artifacts

Downloading the document in PDF format

Downloading the original document uploaded to OfficeDrop

The page in the “display” format

The page in the “thumbnail” format

The page in the “snippet_full” format

The page in full resolution

Sharing a resource

Shared documents

Shared folders

Glossary

OfficeDrop

Solutions

Digital Office Add Ons

OfficeDrop