Seller API description

Introduction

The mobile.de Seller-API is an interface to store seller vehicle and user data to the mobile.de-database and make them available on the platform as classified ads. It enables API partners to carry out all necessary operations to manage the full lifecycle of listings from creation to deletion.

Sandbox

For testing purposes a sandbox is available at this base URL:
https://services.mobile.de/ using a proxy server.

This sandbox offers the full functionality of the seller API as described in this document. Furthermore you can verify your results by retrieving the XML data of the ads from the seller API itself or by logging into the dealer area of the assigned sandbox account. Please contact Customer Service for Sandbox access.

Technical basics

The API is available at this base URL:
https://services.mobile.de/

In general the API follows the conventions for REST-APIs. All communication is done via HTTP, the correct combination of request methods and URL trigger the actions of the API.
You can find more information about the REST principle here:http://en.wikipedia.org/wiki/Representational_State_Transfer

API user / TSP

An "API user" is the entity that has an "API account" and uses that account to post ads for one or more sellers (which are linked to that account) to the API. Usually the "API user" is a TSP ("Transfer Service Provider") which posts ads for a larger number of sellers.

Sites / site-id / site-key

mobile.de runs different websites in different countries. For example www.mobile.dein Germany and www.automobile.it in Italy. Each of those sites is identified by asite-key.
You can find a full list of the site-keys in our reference data.

However this API is for all of those sites but for the various sites there may exist some different rules for offering a vehicle and different sets of reference data (make and model sets, vehicle classes and feature sets) might be visible.

Each seller is at home on one of these sites. When posting ads, they are created on the site where the seller is at home and so the specific reference data and validation rules of that site apply to new ads.

This is why you should know on which site your sellers are at home. See Retrieve all your sellers to find out the site-keys of your sellers.

Authorization / permissions

In order to upload listings on behalf of mobile.de customers you'll need to register as an API user on the mobile.de platform. Please contact Customer Support for further details about this activation process!

There are 3 authentication methods. Each of them requires a valid API user as described above and the only difference between them is a technical aspect how the user credentials are passed to the service.

1. HTTP Basic Authentication (Recommended)
   

   The user must be authenticated with a username and password using the HTTP basic authentication scheme.
   For detailed information on HTTP basic authentication seehttp://en.wikipedia.org/wiki/Basic_access_authentication orhttp://tools.ietf.org/html/rfc1945#section-10.2.

   During the activation process the Customer Support will provide you with instructions how to get the access credentials. The credentials are unique for each API user and do not dependent on sellers or ads.

   Note:This authentication method uses the same credentials as the FTP Upload-Interface.
   Please contact customer supportfor details.

2. Seller API Token (Deprecated)
   

   This is the method used for the existing users and the tokens won't be issued for the new users. The Seller-API Token is a character string which (as a special HTTP header) has to be included for each API call.
   

   HTTP header element	Description
   X-MOBILE-SELLER-TOKEN	Static token of the registered API user

   
   Example auth token HTTP header:
   

   X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf

   Note:In the near future this method will be phased out in favor of the more secure http basic authentication method - please see the previous point for details.

3. Username and Password as the Token (Temporary)

   This method has been introduced to make it easier for the API users to migrate from the token authentication to the recommended http basic authentication.

   It uses the same credentials as the http basic authentication but the username and passwordare provided via the X-MOBILE-SELLER-TOKEN header in the following format:

   HTTP header element	Description
   X-MOBILE-SELLER-TOKEN	username:password

   The value of the header is the username and the password separated by the ":" (colon character). The motivation here is to allow the API users switching to the more secure authentication method (username and password) without changing the actual scheme. Switching to this method is as simple as standard procedure of changing the Seller-API Token.

   Example auth token HTTP header:
   

   X-MOBILE-SELLER-TOKEN: myuser:mypassword

For handling ads for dealer sellers, those sellers need to be linked to your API account.
Please note: The seller-key is not the customer-number.
There is a special API call which gives you a list of all sellers that are linked to your account including their seller-key and customer-number (in case it's a dealer).

Concurrency

Do not send multible requests for the same ad at the same time. Always wait for the request to be finished before sending the next one (in scope of the same ad) or you will run into problems.
E.g. do not update one ad's images while another image-update-call for the same ad is still in progress.

XML format and versioning

XML schema files

• Have a look at the XML schema definition to understand what data format is used for communicating wit the seller API.
• Also see our general XML notes.

Advice

• In our XML schema many elements are contained in a sequence. When you create your XML data, make sure the elements you create are in the same order as in the schema.
  Otherwise, the XML validation will fail.

Versioning

To remain backward compatible (when we do major changes to our XML schema), the API is able to handle different schema versions. You have to tell the API which version you send or expect.

This is done by the default HTTP header fields Content-Type and Accept.
The Content-Type (for POST and PUT) or Accept (for GET) header contains a media type (also see http://en.wikipedia.org/wiki/Internet_media_type) and must be explicitly set for each request.

The header value is the media type and each media type refers to an XML schema. This document only refers to the newest an best supported media types and XML schemas. Here is a list of the media types:

Reference data

Parts of the XML refer to our reference data. Here you find reference tables for the enumerated fields, like features, colors, makes, models and others.

Validation and error handling

Most errors occur when sending ad data to the API. Sending invalid data results in an HTTP status code 400 (bad request). The validation and error handling for this use case is handled in this section.
For other errors, like authorization and not-found errors see the complete list ofHTTP response status codes.

Validation

The API checks for errors on two different levels:

Parsing and XML validation

On this level the XML parser tries to read the XML data and validate it according to our XML schema. Some examples of issues that cause this validation level to fail:

• The data was no XML data (not well formed XML).
• The elements or attributes contained invalid data e.g. non numeric data in numeric elements.
• Character encoding issues.
• Required elements and/or attributes are missing.

As the schema is also used for outgoing data (after applying various privacy filters), it is not very strict concerning mandatory elements and attributes.
But there are numerous checks for required data in the next validation level.

Semantic validation

Semantic validation checks for various business rules. Examples:

• A new car should not have a mileage > 500km or/and a first registration date.
• The model description must not be empty.

Please note that semantic validation rules may depend on the seller's site-key.
For example, some rules apply only for ads of sellers with a site-key GERMANY but not forads of a seller with site-key FRANCE.

Error response

Once you have caused a validation error on either level, the API will answer with an HTTP status 400.

To find out what the exact error is, have a look at the returned XML content which is sent in the message body. It contains a list of error elements, each with an error key. There may also be an optional message attribute which is a localized description of the error key.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errors>
    <error key="vehicle-empty"/>
    <error key="price-empty"/>
    <error key="street-contains-url" message="Das Feld Straße darf keine URL enthalten"/>
</errors>

For a selection of most common error codes see Semantic Rules.

HTTP response status codes

200 (OK)

A successful API call will be indicated by an HTTP-status code 200 (OK).

201 (created)

When you have posted something, a successful API call will be indicated by an HTTP-status code 201 (created). Have a look at the returned HTTP header Location.
It contains the URL of the newly created resource and you should memorize at least the id or key of that item, which you can find at the end of the URL.

Location: https://services.mobile.de/seller-api/sellers/123/ads/456

204 (No Content)

After deleting something (HTTP method DELETE) a successful API call will be indicated by an HTTP-status code 204 (No Content), though that resource no longer exists.

400 (bad request)

This code is returned when there is something wrong with the content that you have sent. See sectionValidation and error handling.

401 (unauthorized)

This code is returned on a wrong/missing token for authentication.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errors>
    <error key="wrong-token"/>
</errors>

If you keep getting authorization errors check the following list of possible error causes:

• Did you register as an API user with mobile.de and had the Customer Support activated your account properly?
  Call Customer Support to register as an API user or ask whether your account has been activated properly.
• Do you send the correct Seller Token with your requests?
  Make sure your requests contain the HTTP Header "X-MOBILE-SELLER-TOKEN" and the Seller Token equals the one provided to you by Customer Support.
  If in doubt, ask Customer Support to resend you the token or generate a new one.

404 (not found)

This status code is returned when you are trying to access a resource that does not exist. In a simple case this can be a typo in the path you are accessing, but this can also have another reason:

From your point of view, only sellers that are linked to your API account are visible. So if you try to read or write data for a seller that is not linked to your account and therefore not existing in your API universe, you will get an HTTP status code 404.

Example:
The seller with the key 123 is linked to your account, the seller with the key 456 is not. Posting an ad to /seller-api/sellers/123/ads results in an HTTP status 201 (created) whereas posting an ad to /seller-api/sellers/456/ads results in an HTTP status 404 (not found).

If you keep getting not found errors, check the following list of possible error causes:

• Do you use the correct seller-key in your requests URLs?
  Make sure you send your requests to the correct URL containing the seller-key of the customer you are servicing.
  Ask Customer Support whether the customer account had been properly set for TSP servicing with your mobile.de TSP account.
• Do you use the correct HTTP method and API service URL?
  Take a look at the API Use Case table provided below and make sure you got the API base URL, resource path and HTTP method right.

5xx

If you receive an HTTP code starting with 5 then we did something wrong. Please contact customer support and report the error.

Resources

Please refer to the following table for an overview of the methods and corresponding calls.

{seller-key} is to be replaced by the seller-key (which is not the customer-number - seeRetrieve all your sellers for a translation method) and{adId} is to be replaced by the ID of the ad.

Retrieve all your sellers

With this call you can get a list of all sellers that are linked to your API account. These are all dealer sellersthat were linked to your account.
The dealer sellers also include their customer-number, this is very useful in case you want to translatecustomer-numbers into seller-keys.

The site-ID is included as well - which is important to know, due to the fact that some validation rules depend on thesite.

Not all fields of the XML will be retrievable, it depends on what you are allowed (permissions) to see.

The result contains also the maximum number of images the seller is allowed to upload per each ad. Please note that this number may vary for different sellers and could change over the time.

Request

Example request-line and headers

GET /seller-api/sellers HTTP/1.0
Host: services.mobile.de
X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf
Accept: application/vnd.de.mobile.seller-v2.0+xml

Response

Example status-line and headers

HTTP/1.1 200 OK
Content-Type: application/vnd.de.mobile.seller-v2.0+xml

Example message-body

<?xml version="1.0" encoding="UTF-8"?>
<sellers
    xmlns="http://services.mobile.de/schema/common/seller-2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://services.mobile.de/schema/common/seller-2.0.xsd"
>
    <seller customerNumber="86" site-id="GERMANY" type="DEALER" key="1499">
        <location-contact company-name="Example Company 1 GmbH"/>
        <settings>
            <max-images value="30"/>
            <used-car-seals>
                <used-car-seal value="VW"/>
                <used-car-seal value="AUDI"/>
            </used-car-seals>
            <automated-exports>
                <automated-export marketplace="ebay-kleinanzeigen.de" eligible="true" active="false"/>
            </automated-exports>
            <video-url value="true"/>
        </settings>
    </seller>
    <seller customerNumber="96" site-id="FRANCE" type="DEALER" key="1509">
        <location-contact company-name="Example Company 2"/>
        <settings>
            <max-images value="15"/>
            <used-car-seals>
                <used-car-seal value="CITROEN"/>
                <used-car-seal value="RENAULT"/>
            </used-car-seals>
            <automated-exports>
                <automated-export marketplace="ebay-kleinanzeigen.de" eligible="true" active="true"/>
            </automated-exports>
            <video-url value="true"/>
        </settings>
    </seller>
</sellers>

Retrieve a single seller

Not all fields of the XML will be populated, it depends on what you are allowed (permissions) to see.

Request

Example request-line and headers

GET /seller-api/sellers/123 HTTP/1.0
Host: services.mobile.de
X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf
Accept: application/vnd.de.mobile.seller-v2.0+xml

Response

Create ad

Please note: you should store the returned ad-key in order to be able to revise the ad, add images to it or delete it later.

Request

Example request-line and headers

POST /seller-api/sellers/123/ads HTTP/1.0 Host: services.mobile.de X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf Content-Type: application/vnd.de.mobile.seller-ad-v1.1+xml

Example message-body

<?xml version="1.0" encoding="UTF-8"?>
<ad xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://services.mobile.de/schema/seller/seller-ad-1.1"
    xmlns:vehicle="http://services.mobile.de/schema/seller/vehicle-1.0"
    xmlns:site-specifics="http://services.mobile.de/schema/seller/site-specifics-1.0"
    xmlns:price="http://services.mobile.de/schema/seller/price-1.0"
    xsi:schemaLocation="http://services.mobile.de/schema/seller/seller-ad-1.1 http://services.mobile.de/schema/seller/seller-ad-1.1.xsd">
    <seller-inventory-key value="fooBar42"/>
    <description>This is really a nice car. The only strange thing is that so called flux capacitor that it is equipped
    with. The previous owner told me that he took it from an old DeLorean. No idea what it is good for.</description>
    <mobile-features>
        <feature>EYE_CATCHER</feature>
        <feature>PAGE_ONE_AD</feature>
        <feature>TOP_OF_PAGE</feature>
    </mobile-features>
    <vehicle:vehicle>
        <vehicle:classification>
            <vehicle:vehicle-class key="Car"/>
            <vehicle:category key="Cabrio"/>
            <vehicle:make key="PORSCHE"/>
            <vehicle:model key="993"/>
        </vehicle:classification>
        <vehicle:model-description value="993 coupe Carrera 4"/>
        <vehicle:damage-and-unrepaired value="false"/>
        <vehicle:accident-damaged value="false"/>
        <vehicle:roadworthy value="true"/>
        <vehicle:features>
            <vehicle:feature key="ALLOY_WHEELS"/>
            <vehicle:feature key="ELECTRIC_WINDOWS"/>
            <vehicle:feature key="IMMOBILIZER"/>
            <vehicle:feature key="ABS"/>
            <vehicle:feature key="ESP"/>
            <vehicle:feature key="HU_AU_NEU"/>
        </vehicle:features>
        <vehicle:specifics>
            <vehicle:exterior-color key="">
                <vehicle:metallic value="false"/>
                <vehicle:manufacturer-color-name value="Kuntergraudunkelbunt"/>
            </vehicle:exterior-color>
            <vehicle:mileage value="142000"/>
            <vehicle:door-count key="TWO_OR_THREE"/>
            <vehicle:fuel key="PETROL"/>
            <vehicle:power value="210"/>
            <vehicle:gearbox key="MANUAL_GEAR"/>
            <vehicle:construction-date value="1997-04-12"/>
            <vehicle:cubic-capacity value="3600"/>
            <vehicle:condition key="USED"/>
            <vehicle:interior-type key="ALCANTARA"/>
            <vehicle:number-of-previous-owners value="1"/>
            <vehicle:parking-assistants>
                <vehicle:parking-assistant key="FRONT_SENSORS"/>
                <vehicle:parking-assistant key="REAR_SENSORS"/>
            </vehicle:parking-assistants>
        </vehicle:specifics>
        <vehicle:site-specifics>
            <site-specifics:first-registration value="1997-09"/>
            <site-specifics:schwacke-code value="2366642"/>
        </vehicle:site-specifics>
    </vehicle:vehicle>
    <price:price type="FIXED" currency="EUR">
        <price:gross-prices>
            <price:consumer-price-amount value="32000.00"/>
        </price:gross-prices>
    </price:price>
</ad>

Response

The response contains a Location header which leads you to the URL of the newly created ad. You find the newad-key at the end of that URL.

Example status-line and headers

HTTP/1.1 201 Created Location: https://services.mobile.de/seller-api/sellers/123/ads/456

Retrieve all ads of a seller

Request

Example request-line and headers

GET /seller-api/sellers/123/ads HTTP/1.0 Host: services.mobile.de X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf Accept: application/vnd.de.mobile.seller-ad-v1.1+xml

Response

Retrieve a single ad

Request

Example request-line and headers

GET /seller-api/sellers/123/ads/456 HTTP/1.0 Host: services.mobile.de X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf Accept: application/vnd.de.mobile.seller-ad-v1.1+xml

Response

Update ad

Request

Example request-line and headers

PUT /seller-api/sellers/123/ads/456 HTTP/1.0 Host: services.mobile.de X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf Content-Type: application/vnd.de.mobile.seller-ad-v1.1+xml

Example message-body

<?xml version="1.0" encoding="UTF-8"?>
<ad ...>
    ...some stuff omitted to make it a shorter example...
</ad>

Response

Example status-line and headers

HTTP/1.1 200 OK

Renew ad

Request

Example request-line and headers

POST /seller-api/sellers/123/ads/456/vehicle-attribute/renewal-date HTTP/1.0
Host: services.mobile.de
X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf
Content-Type: application/vnd.de.mobile.seller-ad-v1.1+xml

Response

Example status-line and headers

HTTP/1.1 204 OK

Delete ad

Note: it is NOT necessary to delete the images before deleting the ad.

Request

Example request-line and headers

DELETE /seller-api/sellers/123/ads/456 HTTP/1.0 Host: services.mobile.de X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf

Response

Example status-line and headers

HTTP/1.1 200 OK

Upload images

The API Images-Handling is done in a way which processes all changes in one call.
mobile.de uses the external picture service to store the images, which results in certain limitations:

• The images have to be in JPG-format.
• The maximum number of images per ad depends on the seller settings. Please refer to the retrieving seller information section for details.
• The images must not be larger than 2097152 bytes.
• The image width + height must not be smaller than 20 pixels.
• The image width + height must not be larger than 9000 pixels.
• The image colorspace must be RGB. CMYK is not possible.
• Calls may take longer duration due to file uploading and storage, so consider checking the timeouts and/or retries in case of an error.

The API call to add images supports two modes:

Add pictures initially

All images, which are related to the ad are added to it via the API in one single call.

The content-type of the request entity must be "multipart/form-data". The content type of a single part must be "image/jpeg". The parts are named "image".

The images are attached to the ad in the same order as you put them into the request.

The response will be a list of image URLs. You have to store those URLs as a reference for future image operations an this ad.

Change pictures

After initially putting images to the ad you can also remove single images, change image order or add other images to the ad.

In this case a single part of the request entity contains either an image in the way described above or the internal image url. A part containing an internal image url must be named "image-ref". Please note that external URLs will be rejected!

Just send another multipart request. You only need to provide binary image data for new images. All existing images are referenced by their picture-service-URLs. In this case the name of the single part is "image-ref". Images that are no longer referenced will be deleted. New images included as binary data will be added. The order in the multipart request becomes the order of the ads images. Have a look at the below example.

Request

Example request-line and headers

PUT /seller-api/sellers/123/ads/456/images HTTP/1.0
Host: services.mobile.de
X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf
Content-Type: multipart/form-data; boundary=vjrLeiXjJaWiU0JzZkUPO1rMcE2HQ-n7XsSx
Accept: application/vnd.de.mobile.seller-ad-v1.1+xml

Example message-body

In this example we re-use two existing images and then on the third position add a new image:

--vjrLeiXjJaWiU0JzZkUPO1rMcE2HQ-n7XsSx
Content-Disposition: form-data; name="image-ref"
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit

https://img.classistatic.de/api/v1/mo-prod/images/46/467621f8-dcca-4c7f-ba2b-5f50942b713b?rule=mo-640.jpg
--vjrLeiXjJaWiU0JzZkUPO1rMcE2HQ-n7XsSx
Content-Disposition: form-data; name="image-ref"
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit

https://img.classistatic.de/api/v1/mo-prod/images/46/467621f9-dcca-4c7f-ba2b-5f50942b713b?rule=mo-640.jpg
--vjrLeiXjJaWiU0JzZkUPO1rMcE2HQ-n7XsSx
Content-Disposition: form-data; name="image"; filename="image.jpg"
Content-Type: image/jpeg
Content-Transfer-Encoding: binary

 ...some binary JPEG data omitted here...
--vjrLeiXjJaWiU0JzZkUPO1rMcE2HQ-n7XsSx--

Response

Example status-line and headers

HTTP/1.1 200 OK
Content-Type: application/vnd.de.mobile.seller-ad-v1.1+xml

Example message-body

<?xml version='1.0' encoding='UTF-8'?>
<images xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://services.mobile.de/schema/seller/seller-ad-1.1"
    xsi:schemaLocation="http://services.mobile.de/schema/seller/seller-ad-1.1 http://services.mobile.de/schema/seller/seller-ad-1.1.xsd">
    <image ref="https://img.classistatic.de/api/v1/mo-prod/images/46/467621f7-dcca-4c7f-ba2b-5f50942b713b?rule=mo-640.jpg"/>
    <image ref="https://img.classistatic.de/api/v1/mo-prod/images/46/467621f8-dcca-4c7f-ba2b-5f50942b713b?rule=mo-640.jpg"/>
    <image ref="https://img.classistatic.de/api/v1/mo-prod/images/46/467621f9-dcca-4c7f-ba2b-5f50942b713b?rule=mo-640.jpg" hash="e4abea3cb9fc16ec9e7a707f8927bff2"/>
</images>

Get all image URLs

Use this API call to receive all Image URLs of an ad.

Request

Example request-line and headers

GET /seller-api/sellers/123/ads/456/images HTTP/1.0
Host: services.mobile.de
X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf
Accept: application/vnd.de.mobile.seller-ad-v1.1+xml

Response

Delete all images

It is NOT required to delete the images before deleting the ad.

Request

Example request-line and headers

DELETE /seller-api/sellers/123/ads/456/images HTTP/1.0
Host: services.mobile.de
X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf

Response

Example status-line and headers

HTTP/1.1 204 No Content

Retrieve ad statistics

It is possible to retrieve important success metrics for an ad. This function delivers strictly private information, which must not be displayed to any other user except the corresponding customer. It is not allow to store this information longer than the duration of the ad it relates to or to aggregate this data.

You need special permission to be able to do this API call.

Request

Example request-line and headers

GET /seller-api/sellers/123/ads/456/statistic HTTP/1.0
Host: services.mobile.de
Accept: application/vnd.de.mobile.ad-statistic-v2.0+xml
X-MOBILE-SELLER-TOKEN: hf76g364gf6gjdsgfhsdgfzf

Response

Impressum / Imprint