Loading ...
edocr
Internet Services
Blog Posts
649
1
Try Now
Log In
Pricing
Edocr API Reference Documentation Premium Account Status Required (update April 6, 2023) Prerequisites Authentication Responses Document Retrieval Get User Document Count GET /api/v1/users/:userguid/documents/count GET /api/v1/users/current/documents/count (user identified by API key) Get User Document List /api/v1/users/:userguid/documents /api/v1/users/current/documents (user identified by API key) Get Single Document /api/v1/documents/:documentId Get Document Analytics /api/v1/documents/:documentId/analytics Document Publishing Publish Document Create Document Update Document Update Metadata and/or URL PUT /api/v1/documents/:documentId Set Document Content PUT /api/v1/documents/:documentId/source Delete Document Collections Get Collections Users Get User /api/v1/users/current (user identified by API key) /api/v1/users/:userguid /api/v1/users?email=foo@bar.com Embedding Documents On External Websites Using the API To Embed Your Documents Hosted Externally To Edocr Downloading Thumbnail Images edocr hosted documents Externally Hosted Documents Optional Arguments Viewer Customization With the API Choosing Individual Components To Hide Customizing Colors Specifying A Document Title Specifying A Start Page Capturing Viewer Events Enabling Annotation Controls Specifying Whether Viewer Should Fit To Height or Width Simple Embeds Managing Your Embedded Document Prerequisites Access to the API requires generation of an API key, which is only available to Premium accounts. You can generate your key under Account Settings -> Integrations -> API Integration. Authentication Authentication is performed by passing the API key, either via setting the “apikey” header in the HTTPS request (all requests must be over HTTPS), or using the apikey query parameter. Responses All requests require apikey as either a query parameter or in the request header. If no API key is provided, or if the API key provided is invalid, the request will be rejected with HTTP status 401, with response body {"errorCode": "Unauthorized"} If the requested item is not found, it will return HTTP status 404, with response body {"errorCode": "NotFound"} If a request is made for an item the requesting user does not have access to (e.g. requesting another user's private document), the API will return HTTP status 403 with response body {"errorCode": "Forbidden" } If some other unexpected error occurs, the API will return a status 580, with a similar response body as the above examples, but the errorCode will vary depending on the cause. Unless otherwise noted, generally a successful will return an HTTP status 200 and the response body will be as outlined below based on the specific request type. Document Retrieval Get User Document Count Gets a count of the number of documents specified by the user identified by “:userGuid”, or the user who’s API key is being used if “current” is provided. GET /api/v1/users/:userguid/documents/count GET /api/v1/users/current/documents/count (user identified by API key) { "count": 42 } Get User Document List Gets a list of public documents specified by the user identified by “:userGuid”, or the user who’s API key is being used if “current” is provided. /api/v1/users/:userguid/documents /api/v1/users/current/documents (user identified by API key) Sample output: [ { "guid": "79edw4e7", "title": "Lorem ipsum dolor", "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla. ", "visibility": "leads", "category": { "id": 3, "name": "Business & Jobs" }, "collection": { "id": 337019, "name": "Research Documents" }, "published": "2016-07-14T20:43:36.000Z" }, { "guid": "xrygk3dv", "title": "An Astounding Work of Fiction", "description": "Stephen King claims this novel made him wet the bed.", "visibility": "marketplace", "category": { "id": 11, "name": "Literature" }, "published": "2016-07-13T22:42:00.000Z" }, { "guid": "qp24yzql", "title": "My Cat", "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla. ", "visibility": "public", "category": { "id": 28, "name": "Nature" }, "published": "2016-02-25T15:46:38.000Z" } ] Attribute Description Values guid Globally unique identifier that uniquely identifies a share. Alphanumeric title Title of the document Text description Description/summary of the document contents Text; limited support for HTML tag formatting visibility Describes the visibility of the document. public - any user can view the document leads - only users who have agreed to share their email may view the document marketplace - only users who purchase the document may view it link - Only users who have the unique private URL may view the document group - Only users who the document have explicitly been shared with may view the document. category The category id and description the document has been placed in collection (optional) The user collection id and description the document was published in, if applicable. Get Single Document /api/v1/documents/:documentId Gets metadata for the document specified by :documentId. The output format is the same as for get user document list, but returns a single JSON object representing the requested document, rather than a list. Get Document Analytics /api/v1/documents/:documentId/analytics Sample output: [ { "view": 1, "date": "2016-05-12" }, { "view": 2, "date": "2016-05-19" }, { "download": 1, "share": { "twitter": 1 }, "date": "2016-07-12" } ] For a given document, returns analytics counts by date. Analytics include views, document downloads (if enabled), social sharing counts (twitter, facebook, linkedin, googleplus, reddit, tumblr, pinterest or email) Document Publishing Publish Document Publishing a document is a 1 or 2 step process depending on whether you are sharing an external resource or a file upload. For URL shares, the external URL can be specified as part of the document metadata that is included in the document creation request. For uploads, you also specify the metadata in the document creation request, and then upload the source document as the final step. Create Document POST /documents { "title": "This is a test URL share document", "url": URL_TO_SHARE, "description": "Detailed description here", "categoryId": 30, "templateId": 2, "customTags": "seo,edocr,api", "collectionId": 0, "download": 0, "printing": 0, "copy": 0, "embed": 0 } Attribute Description Values title Name for the document. Required. Alphanumeric url External URL that specifies the document contents. (Required if URL share) Valid URL description Description/summary of the document contents Text; limited support for HTML tag formatting categoryId Specifies document category. Default is “30” (Other) Integer templateId Specify a custom template to use instead of the system default (2). Integer, default 2 customTags Specify custom tags in addition to the ones automatically generated by edocr.. Comma separated string of tags. collectionId Specify a collection id the document should Integer be published to (default is “My Documents”) download 1 = allow document to be downloaded 0 = do not allow document downloads Integer, default 1 printing 1 = allow document to be printed 0 = do not allow document printing Integer, default 1 embed 1 = allow document to be embedded 0 = do not allow embeds Integer, default 1 Returns documentId, eg { documentId: <edocr document id> } You will need this document id if you subsequently wish to update the document’s metadata or content, or if you wish to delete the document. Update Document Update Metadata and/or URL PUT /api/v1/documents/:documentId See Create Document for valid attributes. Set Document Content PUT /api/v1/documents/:documentId/source Upload the document contents. The document type should be specified in the Content-Type header. Here’s a simple example in nodejs: const filedata = fs.readFileSync(“some.pdf”); try { const {status, data} = await axios({ method: 'PUT', url: `https://edocr.com/api/v1/documents/${documentId}/source`, data: filedata, headers: { 'Content-Type': ‘application/pdf’, 'apikey': API_KEY, 'Content-Length': filedata.length } }); } catch(err) { console.error(err); reject(err); } Delete Document DELETE /api/v1/documents/:documentId Collections Get Collections GET /api/v1/collections Returns a list of collections that your API key has access to. Example response: [ { "collectionId": <collection_id>, "name": "a collection", "url": "https://www.edocr.com/user/<owner_sharename>/collections/acollection" }, { "collectionId": <collection_id>, "name": "another collection", "url": "https://www.edocr.com/user/<owner_sharename>/collections/anothercollection" } ] Users Get User You can retrieve a user’s public information using multiple methods. To get the user associated with the API key, use: /api/v1/users/current (user identified by API key) If you know a specific user’s GUID, you can use: /api/v1/users/:userguid You can also search for a user by their email address, if they have shared it as part of their public profile. (NOTE: to protect privacy, it will not find users by their login email address) /api/v1/users?email=foo@bar.com Finally, if you know the edocr user name, you can search by that as well. /api/v1/users?userName=xxxxxx Sample output: { "guid": "0C3BB609-1E40-4B1D-9D4D-667F9049D1A9", "userName": "edocrUser", "displayName": "edocr user", "logo": "https://s3.amazonaws.com/dev.edocr.com/0C3BB609-1E40-4B1D-9D4D-667F9049D1A9/wng wpdme.png", "bio": "<p>This is a paragraph of text all about me</p>", "contact": { "address": "123 Main St", "address2": "Suite 1337", "city": "Tampa", "state": "FL", "postalCode": "33601", "country": "US", "phone": "8135551212", "email": "foo@bar.com", "facebook": "http://edocr.com", "twitter": "MyTwitter" } } Embedding Documents On External Websites As a premium user, you have the ability to embed your edocr documents with our advanced viewer directly on your website. This gives you the ability to update content through our API without having to update anything on your website. For example, you could post a single document with a current price list, and embed that on a page in your website. Then you can use our API to update your document with current prices whenever they change, without having to touch your website! There are two methods available for embedding your documents depending on whether the source documents are stored on edocr or not. Using the API To Embed Your Documents Hosted Externally To Edocr Premium accounts have access to the API which allows for more flexibility for your embedded documents. You can customize elements of the viewer and you don’t have to upload the documents to your edocr account. First you must generate an API key, which requires a premium account. You can generate your key under Account Settings -> Integrations -> API Integration. This key will be used to identify you when making API requests. Now using this key, embed your iframe as shown below. You can customize your iframe with any standard iframe attributes; this is just a simple example. <iframe src="https://www.edocr.com/api/v1/viewer?document=<publicly accessible URL>&key=<your edocr API key>" /> Downloading Thumbnail Images There are two methods of generating thumbnail images, depending on whether you are generating them from an edocr hosted document or an externally hosted document. The expected response is the image data; there is no need to poll. edocr hosted documents /api/v1/documents/:documentId/thumbnail?key=<your edocr API key> Externally Hosted Documents /api/v1/thumbnail?key=<your edocr API key>&document=<publicly accessible document URL> Optional Arguments contentType: You may optionally specify `contentType` (‘png’ or ‘jpeg’, defaults to jpeg). maxHeight, maxWidth: Specifies the maximum dimensions of the image. By default the dimensions are the actual image size. Note: If you set either maxHeight or maxWidth, you must pass both. scale: Set the viewer’s initial zoom scale; specified as a decimal between 0 and 1. Example: /api/v1/thumbnail?key=<your edocr API key>&document=<publicly accessible URL>&contentType=png&maxHeight=512&maxWidth=512 Viewer Customization With the API Choosing Individual Components To Hide The API accepts a comma separated list of individual components to hide so they are not displayed (by default all controls are shown) using the hidden query parameter. The following options are currently available: Print, DownloadOriginal, DownloadAsPdf, SelectText, MagnifierTool, SelectToZoom, RotateDocument, RotatePage, FitToHeight, FitToWidth, Zoom, toolbar, branding Notes: - toolbar is a shortcut that hides the entire lower toolbar and all its buttons - Zoom hides the entire bottom bar - branding removes the “Powered by edocr” in the top bar. Customizing Colors Colors should be specified using a 6 digit hex code omitting the leading ‘#’. Available color customizations are: upperToolbarColor, lowerToolbarColor, bottomToolbarColor,fontColor buttonColor Notes: - fontColor applies to all text as well as the button icon foreground colors - buttonColor changes the background color of the buttons Below is a visual guide to the various component names that can be customized: Below is an example API call that yields some questionable color choices and hides the “Download original” and “Print” buttons. https://www.edocr.com/api/v1/viewer?document=https://myserver.com/myfile.pdf&key =<edocr_api_key>&fontColor=ff0000&upperToolbarColor=ccccff&bottomToolbarColor=cc cc11&lowerToolbarColor=aaffaa&hidden=branding,Print,DownloadOriginal Specifying A Document Title Add the title= argument to optionally specify a document title (defaults to ‘Document’) e.g. https://www.edocr.com/api/v1/viewer?document=https://myserver.com/myfile. pdf&title=My%20Cool%20Document&key=<edocr_api_key> In this example the document’s title will be set to “My Cool Document” Specifying A Start Page Add the page= argument to specify the start page (which defaults to 1). e.g. https://www.edocr.com/api/v1/viewer?document=https://myserver.com/myfile. pdf&page=4&key=<edocr_api_key> In this example the viewer will begin displaying the document starting with page 4. Capturing Viewer Events Because of security restrictions with cross-domain communication between an iframe and it’s enclosing document, listening for viewer events requires listening for message events implemented via Window.postMessage(). Below is a simple example where the enclosing document’s ‘page Number’ span is updated whenever a ‘PageChanged’ message is triggered in the iframe by a page turn event. There’s also code to check when the viewer has completed loading the document or if the viewer encounters an error loading it. The message is received by the enclosing document where the application code can take further action. To determine the event, you need to look at event.data.edocrEvent where “event” is the variable name of the event variable passed to the listener. In the examples below, it’s named ‘e’. Below the example is information on the data available for each event type. <html> <body> <iframe id="iframe" width="800px" height="600px" src="https://dev.edocr.com/api/v1/viewer?page=3&document=https://www.irs.gov/pub /irs-pdf/fw9.pdf&key=<edocr API key>"> </iframe> <div width="100%" style="background-color: #11111"> Page <span id="pageNumber"></span> of <span id="pageCount"></span> </div> <script> const iframe = document.getElementById('iframe'); iframe.addEventListener("load", () => { // add listener for messages from embedded viewer iframe window.addEventListener("message", e => { // handle event in application here ... if(e.data.edocrEvent == 'PageChanged') { document.getElementById('pageNumber').innerHTML = e.data.pageNumber; document.getElementById('pageCount').innerHTML = e.data.pageCount; } else if(e.data.edocrEvent == 'ViewerReady') { console.log("****** Viewer Ready!"); } else if(e.data.edocrEvent == 'ViewingSessionFailed') { console.warn('****** Viewing session error', e.data.details); } }) }) </script> </body> </html> These are the type of events that are currently supported. PageChanged This is triggered whenever the user changes the current page in the viewer. It also includes a pageNumber, which is the new current page, and pageCount, which is the total number of pages in the document. ViewerReady Indicates the viewer has finished initializing and document is ready to be interacted with. There is no additional information in this event. ViewingSessionFailed Indicates there was a problem initializing the viewing session. The details member will contain more information about why the viewing session failed. Here’s an example where the source document that was passed was not found: { statusCode: 480, errorCode: "CouldNotGetRemoteResource", ip: "1.2.3.4", sourceServerStatus: 404, | The individual members of the error details object are as follows: - statusCode - This is the HTTP status returned by PrizmDoc Application Services. In this example, 480 represents a bad input (because the URL we passed was invalid) - errorCode - This is the error code returned by PrizmDoc Application Services, or ClientError in the case of an error encountered by the viewer client itself. If a ClientError occurs you should copy the contents of the error object and contact edocr support for further assistance. - ip - This is the ip address of the server the document retrieval attempt was made to - sourceServerStatus - Whenever edocr encounters an error from PAS generating the viewing session, we query the source document directly to gather more information on why it could not be retrieved. In this example, the source server returned a 404 for the document Enabling Annotation Controls Add the enableAnnotations=true argument to enable annotation controls in the toolbar. The user will be able to print or download the annotated version, as long as you have not also disabled the print and/or download buttons.. e.g. https://www.edocr.com/api/v1/viewer?document=https://myserver.com/myfile. pdf&enableAnnotations=true&key=<edocr_api_key> In this example the viewer will begin displaying the document starting with page 4. Specifying Whether Viewer Should Fit To Height or Width By default, the viewer automatically fits the content to fit the maximum width. You can explictly set the behavior by supplying the “fitTo” option, valid values are “height” or “width” (the default). e.g. https://www.edocr.com/api/v1/viewer?document=https://myserver.com/myfile. pdf&fitTo=height&key=<edocr_api_key> Simple Embeds If you don’t wish to use the API, there is an alternative method for embeds, that relies on you having the document stored in your edocr account. Once you have posted your document, either through the UI or web interface, you need to determine your document id. The id is returned by the public API call used to upload the document. If you are using the web UI instead of the public API to upload your documents, The document id is the string you see in between slashes after the initial /v. For example, if you are viewing your document and see the URL in the address bar, in the below example the document id would be dzzpgq4d Now, in the HTML document on your web page, you just need to add the HTML to embed that document. If you press the embed button in the document viewer, you’ll get a popup with HTML for several different types of embed: - Default Viewer - Just displays the document itself in the edocr viewer - Follow Profile - Displays the document as well as a link to follow the publisher’s profile - Follow Collection - DIsplays the document as well as a link to follow the collection containing the document - Thumbnail - Provides a thumbnail image only with a link to the document on edocr You can even click the clipboard button to get the HTML automatically copied into your clipboard for pasting to your code editor (if you’re doing anything other than the default viewer, this is probably the best way to start since some image paths will only be available with the generated code). For reference, here is the default HTML for the different types (some values replaced with placeholders). Width and height can be customized to whatever best fits your content <!-- Default HTML Viewer --> <div style="text-align: center;"> <iframe height="550" width="425" src="https://www.edocr.com/embed/<document_id>"> </iframe> </div> <!-- Follow Profile Viewer --> <div style="text-align: center;"> <iframe height="550" width="425" src="https://www.edocr.com/embed/<document_id>"> </iframe> <p style="text-align: center; font-size: .8em;"> <form target="_blank" action="https://www.edocr.com/follow/<document_id>/profile"> <input type="submit" value="Follow Profile"> </form> </div> <!-- Follow Collection Viewer --> <div style="text-align: center;"> <iframe height="550" width="425" src="https://www.edocr.com/embed/<document_id>"></iframe><p style="text-align: center; font-size: .8em;"> <form target="_blank" action="https://www.edocr.com/follow/<document_id>/collection"> <input type="submit" value="Follow Collection"> </form> </div> <!-- Thumbnail only --> <div style="text-align: center;"> <a style="display: block; margin: 5px auto;" href="https://www.edocr.com/v/<document_id>" target="_blank"> <img style="max-width: 300px;" src="<url_to_thumbnail_image>" alt="Embeddable Viewer" /> </a> <p style="text-align: center; font-size: .8em;"> </div> Managing Your Embedded Document Once your document has been created, you can update it one of two ways: 1. Using the UI, simply edit the document and republish. It will retain the original URL and you won’t have to change anything on your website. 2. Use the public API endpoint Update Metadata to update information about the document, or to specify a different URL in the case of a URL share. Use the public API endpoint Set Document Content to change the file contents In either case, the URL of your document will remain the same, and changes should be reflected immediately.
