Crocodoc has joined Box! Read more here

API › Overview

The Crocodoc API lets you upload documents and then generate secure and customized viewing sessions for them. Our API is based on REST principles and generally returns JSON encoded responses unless otherwise noted. All API access requires HTTPS. The base URL for all requests is https://crocodoc.com/api/v2.

The token parameter is your API token and is required in all requests, so they can be associated with your account. Keep your API token confidential. Anyone who knows it can make API requests on your account's behalf.

API request parameters should be passed using the query string for API methods that require GET. API request parameters should be passed as form fields for API methods that require POST.

In review:

  • All API requests require HTTPS
  • Keep your API token confidential
  • Use POST or GET parameters as specified

Documents

Upload a document

POST https://crocodoc.com/api/v2/document/upload try it out ▸

Document upload requests let you submit documents to Crocodoc for conversion. Although you will receive a response to an upload request quickly, the actual conversion process happens asynchronously. As such, receiving a successful response to an upload request does not imply the document has finished converting or that it is immediately available for viewing.

Request parameters

  • token - Your Crocodoc API token.

One, and only one, of the following:

  • url - The URL of the document to be converted.
  • file - The file as part of a multi-part POST.

Sample request:

curl "https://crocodoc.com/api/v2/document/upload" --data "token=${API_TOKEN}&url=http://web.crocodoc.com/files/test-simple.pdf"
        

Response properties

  • uuid - The uuid assigned to the document.
  • error - Only exists if an error occurs. Provides a short description of why the upload request failed. Some reasons why an upload request may fail include your rate limit being exceeded or a document url or file not being specified.

You should be sure to persist the document's uuid since it is required for all other document actions such as viewing and deleting.

Sample response:

{
  "uuid": "8e5b0721-26c4-11df-b354-002170de47d3"
}
        

Check document status

GET https://crocodoc.com/api/v2/document/status try it out ▸

Gets the current status of the documents listed in the uuids parameter. This method is often polled starting shortly after uploading a document to determine when the document has been successfully converted and is viewable.

Request parameters

  • token
  • uuids - A comma delimited list of document uuids.

Sample request:

curl "https://crocodoc.com/api/v2/document/status?token=${API_TOKEN}&uuids=6faad04f-5409-4173-87aa-97c1fd1f35ad,7cf917de-2246-4ac3-adab-791a49454180"
        

Response properties

The response to a valid status request contains an array of objects; one for each requested document. Each object has the following properties:

  • uuid - The document's uuid.
  • status - Current state of the document. Possible values (described below) include QUEUED, PROCESSING, DONE, ERROR.

    Document status guide:

    • QUEUED - document conversion has not yet begun
    • PROCESSING - document conversion is in process
    • DONE - the document was successfully converted
    • ERROR - an error has occurred during document conversion
  • viewable - Indicates if the document is available for viewing.
  • error - Only exists if the document's status is ERROR. Provides a short explanation of why the document conversion failed. Some reasons a document may fail to convert include the file being corrupt, password-protected, or too large to process.

Sample response:

[ {
    "uuid": "7cf917de-2246-4ac3-adab-791a49454180",
    "status": "DONE",
    "viewable": true
  },
  {
    "uuid": "6faad04f-5409-4173-87aa-97c1fd1f35ad",
    "status": "ERROR",
    "viewable": false,
    "error": "password protected"
  } ]
        

Delete a document

POST https://crocodoc.com/api/v2/document/delete try it out ▸

The delete method permanently deletes all database records and assets associated with a given document.

Request parameters

  • token
  • uuid - The uuid of the document to be deleted.

Sample request:

curl "https://crocodoc.com/api/v2/document/delete" --data "token=${API_TOKEN}&uuid=7cf917de-2246-4ac3-adab-791a49454180"
        

Response

The response of a successful delete request is the boolean value true.

Sample response:

true
        

Session-based viewing

Create a session

POST https://crocodoc.com/api/v2/session/create try it out ▸

Crocodoc uses session-based viewing to ensure that documents are displayed in a secure manner. There are many options available when creating a session as discussed below. Sessions expire 60 minutes after they are generated. A generated session string should be used with the document view method described below to allow users to view and possibly edit a document.

Request parameters

  • token
  • uuid - The uuid of the document for which a session is being created.

Optional parameters:

  • editable - Allows users to create annotations and comments while viewing the document. Default: false
  • user - A user ID and name joined with a comma (e.g.: 1337,Peter). The ID should be a non-negative signed 32-bit integer (0 <= ID <= 2,147,483,647) and unique for each user across your application's userbase. The user name will be shown in the viewer to attribute annotations and comments to their author. Required if editable is true
    User IDs are required to allow both you and Crocodoc to track the author of a given annotation. Examples of their use include controlling who sees which annotations via the filter parameter below or controling which annotations are included when downloading a marked-up PDF.
  • filter - Limits which users' annotations and comments are shown. Possible values are: all, none, or a comma-separated list of user IDs as specified in the user field. Default: all

    Example filter values:
    all
    none
    1337
    1337,78499,2147483647

  • admin - Allows the user to modify or delete any annotations and comments; including those belonging to other users. By default, users may only modify/delete their own annotations or reply to other users' comments. Default: false
  • downloadable - Allows the user to download the original document. Default: false
  • copyprotected - Prevents document text selection. Although copying text will still be technically possible since it's just HTML, enabling this option makes doing so difficult. Default: false
  • demo - Prevents document changes such as creating, editing, or deleting annotations from being persisted. Default: false
  • sidebar - Sets whether the viewer sidebar (used for listing annotations) is included. Possible values (described below) include none, auto, collapse, visible. Default: none

    Option descriptions:
    none - a sidebar will not be included
    collapse - a collapsed sidebar will be included
    visible - an opened sidebar will be included
    auto - an opened sidebar will be included only if the document has annotations

Sample request:

curl "https://crocodoc.com/api/v2/session/create" --data "token=${API_TOKEN}&uuid=6faad04f-5409-4173-87aa-97c1fd1f35ad"
        

Response properties

  • session - Ephemeral session string.

Sample response:

{
  "session": "CFAmd3Qjm_2ehBI7HyndnXKsDrQXJ7jHCuzcRv_V4FAgbSmaBkFrDRS8KX8m-Ur9MdZFbH3ykKdZ7cZswFqrDKX965nba9-MW0DiiA"
}
        

View a document

To view a document, you must first generate a session using the session creation method described above. The URL to view a document with a generated session can be made by replacing <session> in the following template:

https://crocodoc.com/view/<session>

These URLs are suitable for use as a top-level window or within an iframe.

Sample view URL:

https://crocodoc.com/view/CFAmd3Qjm_2ehBI7HyndnXKsDrQXJ7jHCuzcRv_V4FAgbSmaBkFrDRS8KX8m-Ur9MdZFbH3ykKdZ7cZswFqrDKX965nba9-MW0DiiA
        

Asset Downloads

Download a document

GET https://crocodoc.com/api/v2/download/document

Download the original document or a version in PDF.

Request parameters

  • token
  • uuid - uuid of the document to download.

Optional parameters:

  • pdf - Download PDF version instead of original document type. Default: false
  • filename - Document filename to use in the Content-Disposition header. Default: doc.<filetype>
  • annotated - Include annotations. If true, downloaded document will be a PDF. Default: false
  • filter - Limit which users' annotations included. Possible values are: all, none, or a comma-separated list of user IDs as supplied in the user field when creating sessions. See the filter parameter of session creation for example values. Default: all

Sample request:

curl "https://crocodoc.com/api/v2/download/document?token=${API_TOKEN}&uuid=6faad04f-5409-4173-87aa-97c1fd1f35ad&filename=annual_report.pdf"
        

Download a thumbnail

GET https://crocodoc.com/api/v2/download/thumbnail

Returns a thumbnail of the document's first page in PNG format. Thumbnails maintain the proper aspect ratio of pages and are bounded by the dimensions specified in the size parameter.

Thumbnails are generated dynamically and are therefore not suitable for hot-linking since they would load much more slowly than static thumbnails. Also note that hotlinking would insecurely expose your API token to your users. Thumbnails should be requested once from your servers and persisted/served with your other static files.

Request parameters

  • token
  • uuid - The uuid of the document to download a thumbnail of.

Optional parameters:

  • size - Maximum dimensions of the thumbnail in the format {width}x{height}. Largest dimensions allowed are 300x300. Default: 100x100

Sample request:

curl "https://crocodoc.com/api/v2/download/thumbnail?token=${API_TOKEN}&uuid=6faad04f-5409-4173-87aa-97c1fd1f35ad&size=80x90"
        

Sample Thumbnail

Download extracted text

GET https://crocodoc.com/api/v2/download/text

Returns the full text from a document. The downloaded text is encoded using UTF-8. The text for each page is separated by the form feed character (U+000C). This method is available only if your account has text extraction enabled. Please contact Crocdoc Support for details.

Request parameters

  • token
  • uuid - The uuid of the document from which to extract the text.

Sample request:

curl "https://crocodoc.com/api/v2/download/text?token=${API_TOKEN}&uuid=6faad04f-5409-4173-87aa-97c1fd1f35ad"
        

Error Handling

Status Codes

The status code of Crocodoc API request responses should be the first part examined to determine if a request was valid and interpreted correctly. Here's a synopsis of the error codes you can receive:

Here's a synopsis of the error codes you can receive:

  • 200 OK - The request was received successfully.
  • 400 Bad Request - There was a problem with your request parameters. Check the error field of the response object for info on what was wrong.
  • 401 Unauthorized - Your API token in the token parameter was either missing or incorrect.
  • 404 Not Found - The API method was not found. Check yor request URL for typos.
  • 405 Method Not Allowed - An incorrect HTTP verb (i.e. GET, POST, etc) was used for the request
  • 5XX - There was an error Crocodoc could not recover from. We are generally notified of these automatically. If they are repeatedly received, you should contact Crocodoc Support.