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
This method requires authentication.
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.
<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>
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 |
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"
}
}
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 |