Skip to main content

POST/document

This method stages a document to be uploaded, and requires the type of document to be uploaded, and the language(s) that the document contains. A successful call returns a documentId value that is then used as a path parameter in an uploadDocument call.

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.

To upload a created document, use the document ID returned from this method's response with the uploadDocument method. See Managing documents for information on creating, uploading, and adding documents to listings.

Input

Resource URI

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

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 authorization code 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 uploaded. For example, a USER_GUIDE_OR_MANUAL or a SAFETY_DATA_SHEET.

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 method. 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.

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.

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: Create a document ID

This sample creates a document ID using provided metadata to be used when uploading a document. Metadata includes documentType and languages.

Input

The inputs are the documentType and languages array.

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

Output

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

Got thoughts? Click the feedback button – your insights help us improve!