Documents Upload Url

Add a document to a user's profile by specifying its location on the web. The document can be automatically added to a folder once it has been converted.

Action: issuu.document.url_upload

Authentication

This method requires authentication.

Request parameters

Name	Data type	Description
apiKey (required)	string	Application key for the account
signature (required)	string	See Signing Requests
slurpUrl (required)	string	URL of document to be uploaded. This location must be public meaning no login or password required to access resource
name	string	Value determining the URL address of the publication `http://issuu.com/<username>/docs/<name>` The name must be 3-50 characters long. Use lowercase letters (a-z), numbers (0-9) and characters (_.-). No spaces allowed. This value must be unique for the account. In case no value is specified this name will be autogenerated
title	string	Title of the publication. If no value is specified the filename of the uploaded document will be used
tags	list	List of keywords describing the content
commentsAllowed	boolean	Can other people comment on this document? Default is "true"
description	string	Description of the document. If left blank the system will try to extract a summary of the content. Max length: 1000 characters
downloadable	boolean	Can other people download the original document? Default is "false"
infoLink	string	URL linking to more information about this document
language	enum	2 char language code. See Language Codes for allowed values
access	enum	Must be "public" or "private" - default is "public". Private documents are not shown in search engines or on issuu.com
explicit	boolean	If the publication contains explicit content this should be set to "true"
category	enum	6 digit code indicating Document category
type	enum	6 digit code indicating Document type
ratingAllowed	boolean	Can other people rate this document? Default is "true"
publishDate	date	Datetime when this document was originally published. Default is at the time of upload. See Dates for formatting rules
folderIds	list	Folders to copy the document to when processing is done. Use method Folders list to find the id of a specific folder
format	enum	Must be "xml" or "json" - default is "xml". See Getting started for further details
jsonCallback	string	function wrapper for JSONP requests. See Getting started for further details

Here is a basic example of an HTML upload form.

HTML

<form action="http://api.issuu.com/1_0" method="post">
  <input type="hidden" name="action" value="issuu.document.url_upload"/>
  <input type="hidden" name="apiKey" value="g0ch5rj9ywztlo022w70naymutm2fbbg"/>
  <input type="text" name="slurpUrl"/>
  <input type="text" name="title"/>
  <textarea name="description"></textarea>
  <input type="submit" value="Upload from URL"/>
</form>

Response parameters

Upon successful upload this method will return information about the document which was just created.

Name	Data type	Description
username	string	The account to which this document was uploaded
name	string	Web name. If no value was supplied this is temporarily set to the documentId
publicationId	string	Unique assigned id of the publication formatted as 32 hex digits. The id remains constant for all revisions of a publication.
revisionId	string	Identifier of the current revision of a publication. When a new revision is uploaded this id will change while the publicationId remains constant. A revisionId is only unique within a given publication.
documentId	string	Concatenated value of revisionId and publicationId (with a hyphen in between).
title	string	Title of the document. If no value was supplied this will be some placeholder value
access	enum	"public" or "private"
state	enum	The state of the document. Immediately after upload this will have value "P" (processing)
category	enum	The category (if any) specified at upload time
type	enum	The type (if any) specified at upload time
orgDocType	enum	Format of the original file. Supported formats include: "pdf", "odt", "doc", "wpd", "sxw", "sxi", "rtf", "odp" and "ppt"
orgDocName	string	The original filename of the uploaded document
origin	enum	Value indicating how the document was created. In this case it is "apiupload"
language	enum	The language (if any) specified at upload time
pageCount	integer	The number of pages in the document. During processing this value is set to 0
publishDate	date	Timestamp for when this document was published
description	string	The description (if any) specified at upload time
tags	list	The tags (if any) specified at upload time
folders	list	the folders the document will be placed in after successful conversion. The folder listing will not show this document during processing or if processing fails

Example responses

XML

<rsp stat="ok">
  <document username="lekkim" name="racing" documentId="090623122351-f691a27cfd744b80b25a2c8f5a51d596" title="Race cars" access="public" state="P" category="012000" type="009000" origin="singleupload" pageCount="0" ep="1245759831" description="Race cars of Le Man 2009">
    <tags>
      <tag value="cars"/>
      <tag value="le man"/>
      <tag value="racing"/>
    </tags>
    <folders>
      <folder id="3935f331-5d5b-4694-86ce-6f26c6dee809"/>
    </folders>
  </document>
</rsp>

JSON

{
    "rsp": {
        "_content": {
            "document": {
                "username": "lekkim",
                "name": "racing",
                "documentId": "090623122351-f691a27cfd744b80b25a2c8f5a51d596",
                "title": "Race cars",
                "access": "public",
                "state": "P",
                "category": "012000",
                "type": "009000",
                "origin": "singleupload",
                "pageCount": 0,
                "ep": 1245759831,
                "description": "Race cars of Le Man 2009",
                "tags": [
                    "cars",
                    "le man",
                    "racing"
                ],
                "folders": [
                    "3935f331-5d5b-4694-86ce-6f26c6dee809"
                ]
            }
        },
        "stat": "ok"
    }
}

Error codes

Code	Message
009	Authentication required
010	Invalid API key
200	Required field is missing
201	Invalid field format
294	Exceeding allowed amount of unlisted publications
295	Exceeding allowed amount of monthly uploads