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 Folders list |
| | | method 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 |