edocr API Reference Documentation
Premium Account Status Required (update February 21, 2024)
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
Convert File to PDF
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
be published to (default is “My Documents”)
Integer
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:
}
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
Convert File to PDF
Here’s an example that does the following:
1. Uploads a local file to edocr for publishing
2. Requests conversion of the file to PDF
3. Queries the API for status of the conversion until it’s finished
4. Downloads the resulting PDF
'use strict';
const fs = require('fs');
const axios = require('axios');
let axiosSession;
const TARGET_URL="https://www.edocr.com"
const API_KEY=""
async function sleep(ms) {
return new Promise(async(resolve, reject) => {
setTimeout(resolve, ms);
});
}
function documentParameters() {
return {
"title": "This is a test document",
// **** REQUIRED PARAMETER
"description": "Document description ", // default ""
"download": 1
// *** MUST SET TO 1 *** default 0
}
}
async function postDocument(documentParameters) {
console.log(`\nAttempt publish document ...`)
const result = await axios(
{
method: 'POST',
url: `${TARGET_URL}/api/v1/documents`,
headers: {'Content-Type': 'application/json', 'apikey': API_KEY},
data: documentParameters
})
const { status, data } = result;
console.log(`postDocument status`, status);
return({ status, data });
}
async function uploadFile(documentId) {
console.log(`read file for document id ${documentId}`);
const filedata = fs.readFileSync('/tmp/file-sample_100kB.docx'); // update to point to
your input file
console.log(`file size = ${filedata.length}`);
try {
const {status, data} = await axios(
{
method: 'PUT',
url: `${TARGET_URL}/api/v1/documents/${documentId}/source`,
data: filedata,
headers: {
'X-Edocr-Convert-To-Pdf': '1',
'Content-Type':
'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
'apikey': API_KEY,
'Content-Length': filedata.length}
});
return({status, data});
} catch(err) {
console.error(err);
throw(err);
}
}
const createDoc = async() => {
const {status, data} = await postDocument(documentParameters());
return ({status, data});
}
const getResult = async(documentId) => {
try {
const {status, data} = await axios(
{
method: 'GET',
url: `${TARGET_URL}/api/v1/documents/${documentId}/pdf`,
headers: {'apikey': API_KEY},
responseType: 'stream'
});
return({status, data});
} catch(err) {
if(err.response) {
return { status: err.response.status }
} else {
throw err;
}
}
}
const writeFile = async (response) => {
return new Promise( async (resolve, reject) => {
const stream =
response.data.pipe(fs.createWriteStream('/tmp/file-sample_100kB.pdf')); // update to
desired output
stream.on("finish", resolve);
})
}
async function go(url, collectionId, repetitions) {
try {
// If this is for an existing document, you can bypass the createDoc
// and uploadFile steps and go directly to the getResult (you must know
// the existing document id, and download must be enabled for the document)
let r1 = await createDoc();
let documentId = r1.data.documentId;
console.log(`Created document id ${documentId}, now uploading ...`);
let r2 = await uploadFile(documentId);
console.log(`uploadFile/publish result: ${r2.status}\n${JSON.stringify(r2.data, null,
2)}`);
let downloaded = false;
await sleep(10000);
while(!downloaded) {
const r3 = await getResult(documentId);
const { status } = r3;
console.log(`status = ${status}`)
if(status == 409) {
await sleep(10000);
} else if(status == 200) {
await writeFile(r3);
downloaded = true;
} else {
console.log(`Unexpected HTTP status: ${status}`);
process.exit(1);
}
}
console.log(`Conversion completed.`);
process.exit(0);
} catch(err) {
if(err.response) {
console.error(`HTTP ${err.response.status}: ${JSON.stringify(err.response.data,
null, 2)}`);
} else {
console.error(err.stack);
}
}
}
go();
Collections
Get Collections
GET /api/v1/collections
Returns a list of collections that your API key has access to. Example response:
[
{
"collectionId": ,
"name": "a collection",
"url":
"https://www.edocr.com/user//collections/acollection"
},
{
"collectionId": ,
"name": "another collection",
"url":
"https://www.edocr.com/user//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": "

This is a paragraph of text all about me

",
"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.

Page of

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=
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=
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

action="https://www.edocr.com/follow//profile">

action="https://www.edocr.com/follow//collection">

href="https://www.edocr.com/v/" target="_blank">
alt="Embeddable Viewer" />

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.