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//docs/ 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.

<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