Skip to main content

POST/document/create_document_from_url

This method downloads a document from the provided URL and adds that document to the user's account. This method requires the URL of the document, the type of document to be uploaded, and the language(s) that the document contains.

When a document is successfully created, the method returns the HTTP Status Code 201 Created. The method returns documentId in the response payload, which you can use to retrieve the document resource. This ID is also returned in the location header, for convenience.

Important! Make sure to capture the document ID value returned in the response payload. This value is required to use the other methods in the document resource, and also needed to associate a document to a listing using the Trading and Inventory APIs.


After creating a document using this method, a getDocument call should be made to check for a documentStatus of ACCEPTED. Only documents with this status can be added to a listing. See Managing documents for more information on creating, uploading, and adding documents to listings.

Input

Resource URI

POST https://api.ebay.com/commerce/media/v1_beta/document/create_document_from_url

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

This method has no URI parameters.

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

HeaderTypeDescription
Content-TypestringThis header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

OAuth scope

This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.inventory

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

Request fields

Input container/fieldTypeDescription
documentTypeDocumentTypeEnum

The type of the document being created. For example, a USER_GUIDE_OR_MANUAL or a SAFETY_DATA_SHEET.

Occurrence: Required

documentUrlstring

The URL of the document being created.

The document referenced by the URL must be a .pdf, .png, .jpg, or .jpeg file, and must be no larger than 10 MB.

Occurrence: Required

languagesarray of LanguageEnum

This array shows the language(s) used in the document.

Occurrence: Required

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
LocationThe location response header returns the getDocument URI.

Response payload

Response fields

Output container/fieldTypeDescription
documentIdstring

The unique identifier of the document to be uploaded.

This value is returned in the response and location header of the createDocument and createDocumentFromUrl methods. This ID can be used with the getDocument and uploadDocument methods, and to add an uploaded document to a listing. See Adding documents to listings for more information.

Occurrence: Always

documentStatusDocumentStatusEnum

The status of the document resource.

For example, the value PENDING_UPLOAD is the initial state when the reference to the document has been created using the createDocument method. When creating a document using the createDocumentFromUrl method, the initial state will be SUBMITTED.

Occurrence: Always

documentTypeDocumentTypeEnum

The type of the document uploaded. For example, USER_GUIDE_OR_MANUAL.

Occurrence: Always

languagesarray of LanguageEnum

This array shows the language(s) used in the document.

Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
201Created
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
190050API_MEDIAREQUESTMissing or invalid ‘languages’ value(s).
190051API_MEDIAREQUESTMissing or invalid ‘documentType’ value.
190055API_MEDIAREQUESTMissing or invalid 'documentUrl' value.
190056API_MEDIAREQUESTMissing or invalid domain in 'documentUrl'.
190057API_MEDIAREQUESTMissing or malformed 'documentUrl'.
190058API_MEDIAREQUESTMissing or invalid 'request'.
190059API_MEDIAREQUESTInvalid value for ‘documentUrl’ was supplied. Failed to download document from 'documentUrl'.
190060API_MEDIAREQUESTInvalid value for ‘documentUrl’ was supplied. Please provide an HTTPS 'documentUrl'.
190061API_MEDIAREQUESTInvalid value for ‘documentUrl’ was supplied. File type could not be detected from ‘documentUrl'.
190062API_MEDIAREQUESTInvalid value for ‘documentUrl’ was supplied. Not an allowed file type for download from ‘documentUrl'.
190063API_MEDIAREQUESTInvalid value for ‘documentUrl’ was supplied. File size exceeds the maximum limit from ‘documentUrl'.

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Download a document from a URL

This sample downloads a document from the provided URL and adds it to the user's account.

Input

The URL of the document (documentUrl) is required when making this call, as well as the documentType and languages of the document.

POSThttps://api.ebay.com/commerce/media/v1_beta/document/create_document_from_url

Output

If the call is successful, an HTTP status of 201 Created will be returned alongside the following payload. If the call is successful, the document will be created and the document ID will be returned in the response payload, as well as the Location header. The response also includes the document ID, status, type, and language(s).