Attachment/Post

This method creates an attachment to a realstate. You cannot create a realestate and an attachment within one request: you can only post an attachment for an existing realestate.

https://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/{username}/realestate/{realEstateId}/attachment/

  • The request has 2 multiparts for pdf and picture attachments. The 1st multipart contains the picture/pdf as binary file for upload to IS24. The 2nd multipart contains the meta data XML or JSON.
  • Links (URLs) can be posted, as well. The body contains the data as XML or JSON and there is no binary attachment.
  • "/" in an external id needs to be url encoded
  • PDF/picture attachments:
    The attachment with:
      - field name/ContentId "attachment" (it has to be written as "attachment")
      - Media Type "multipart/form-data"
      - Content-Transfer-Encoding: binary
      - Content-Type: image/jpeg; name=filename.jpg  
    Meta data with:
      - Field name/ContentId "metadata" (it has to be written as "metadata")
      - Content-Type: application/xml name=body.xml
      - Content-Transfer-Encoding: binary 
      - Content-Disposition: form-data; name="metadata" filename="body.xml"

You must provide the following HTTP headers:

  • XML (Accept: application/xml)
  • JSON (Accept: application/json)

Authorization requirements

A System Key and an authenticated user are required for this operation:

Please use a secure connection (https) for this operation.

Request

Query Parameters

  • none

Path Parameters

  • Username: the username which the user uses for logging in to www.immobilienscout24.

  • Username: "me" can be used instead of the username, when the user is logged in by 3-legged oauth. This won't work if you have > 1 User in your application.
  • Realestateid: the unique scout object ID, which is resturned with POST REALESTATE.
  • NEW: You can work with your own realestate id as identifier for the realestate object by adding the prefix "ext-": https://... realestate/ext-{your object id}/attachment/{id}/....

Picture upload: Java example

  • The client application, which holds the picture files', must add these one for one (one image per request) as binary "image/jpeg" (other picture formats are allowed, too) part of the multipart body to the ContentId "attachment" to the request.
  • The body's other multipart of the typ "application/json" (or "application/xml") is named "metadata" and contains the description to the image as XML or JSON.
  • The error message ERROR_COMMON_RESOURCE_NOT_FOUND is returned, if false field names /contentIds are being used (meta data, attachment).
  • PHP example: the PHP-SDK contains picture upload.
  • Picture Upload: minimal length of the file name is 4 characters.
// we use the javax.mail API
File imageFile = new File("/path/imageToUpload.jpeg");
File metadataFile = new File("/path/metadataToUpload.json");
PostMethod filePost = new PostMethod("http://host/../attachment");
Part[] parts = {
new FilePart("metadata", metadataFile, "application/json", "UTF8"),
new FilePart("attachment", imageFile, "image/jpeg", null);
};
filePost.setRequestEntity(
new MultipartRequestEntity(parts, filePost.getParams()) ); HttpClient client = new HttpClient(); int status = client.executeMethod(filePost);

Requests (XML)

Example for picture

Title: maximal length is 30 characters

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
POST https://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/999999/realestate/65053776/attachment HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: multipart/form-data; boundary="----=_Part_18_4891264.1339145957290"
Content-Length: 10001
 
------=_Part_18_4891264.1339145957290
 
Content-Type: application/xml; name=body.xml
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="metadata"; filename="body.xml"
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<common:attachment xsi:type="common:Picture" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:ns3="http://rest.immobilienscout24.de/schema/platform/gis/1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <title>Kochecke</title>
    <externalId>kitchen2</externalId>
    <externalCheckSum>your generated checksum</externalCheckSum>
    <floorplan>false</floorplan>
    <titlePicture>false</titlePicture>
</common:attachment>
 
------=_Part_18_4891264.1339145957290
 
Content-Type: image/jpeg; name=mockito_logo.jpg
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="attachment"; filename="mockito_logo.jpg"
PICTURE-BINARY DATA
------=_Part_18_4891264.1339145957290

Example for PDF

Title: maximal length is 30 characters

 --5994e50bd71cd6d34a268c5c82e970c0
Content-Type: application/xml; name=body.xml
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="metadata"; filename="testpdf.pdf"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<common:attachment xsi:type="common:PDFDocument" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:ns3="http://rest.immobilienscout24.de/schema/platform/gis/1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<title>Kochecke</title>
<externalId>kitchen2</externalId>
<externalCheckSum>your generated checksum</externalCheckSum>
<floorplan>false</floorplan>
</common:attachment>

--5994e50bd71cd6d34a268c5c82e970c0

Content-Type: ; name=testpdf.pdf
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="attachment"; filename="testpdf.pdf"


--5994e50bd71cd6d34a268c5c82e970c0--

Example for streaming video with videoId

Detailed protocol steps

1. Request a ticket for upload:

GET https://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/999999/videouploadticket

The upload ticket as response in xml:

<videoupload:videoUploadTicket xmlns:videoupload="http://rest.immobilienscout24.de/schema/videoupload/1.0">
    <uploadUrl>http://upload.screen9.com/media/5pbVk1K-Hvh...</uploadUrl>
    <validUntil>2013-09-10T13:38:25.885+02:00</validUntil>
    <videoId>5-Pcp7uSaZl1RGH1zc6ASA</videoId>
    <auth>FwPF_wqMSGidcoTVv3nXciA8H........wnRO9Rs-Q</auth>
</videoupload:videoUploadTicket>

or in json:

{
    "videoupload.videoUploadTicket": {
        "uploadUrl": "http://upload.screen9.com/media/5pbVk1K-Hvh...",
        "validUntil": "2013-09-10T13:38:25.885+02:00",
        "videoId": "5-Pcp7uSaZl1RGH1zc6ASA",
        "auth": "FwPF_wqMSGidcoTVv3nXciA8H........wnRO9Rs-Q"
    }
}

2. Upload your video to screen9 (see uploadUrl-property of upload ticket above) as multipart request with "auth"-property from upload ticket as first part and your video as second part:

POST http://upload.screen9.com/media/5pbVk1K-Hvh... HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: multipart/form-data; boundary="----=_Part_1_31700508.1378812505910"
MIME-Version: 1.0
Content-Length: 902003
Host: csp.picsearch.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
 
 
------=_Part_1_31700508.1378812505910
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Content-Disposition: form-data; name="auth"
 
FwPF_wqMSGidcoTVv3nXciA8H........wnRO9Rs-Q
------=_Part_1_31700508.1378812505910
Content-Type: application/octet-stream; name=vomUndZumStein
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="videofile"; filename="vomUndZumStein"
 
<<<Streaming Video BINARY DATA>>>

3. Post to rest api a new video attachment with a videoId of pre-uploaded screen9-video(see videoId-property in uploadTicket above)

Note: the video file at screen9 will be deleted by deleting of last referencing attachment at is24

POST https://rest.immobiliensout24.de/restapi/api/offer/v1.0/user/{userid}/realestate/{id}/attachment HTTP/1.1 Accept-Encoding: gzip,deflate Content-Type: application/xml Authorization: Basic TVdfQVBJLUR1bW15X01lcmt6ZXR0ZWxfMTpTZWt0a29ya2Vu Systemauthorization: Basic aXMyNC10ZXN0c3lzdGVtS2V5OnNmZnNkZjlIM2trUmxsMTQ=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<common:attachment xsi:type="common:StreamingVideo" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0"
xmlns:ns3="http://rest.immobilienscout24.de/schema/platform/gis/1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<title>bla</title>
<externalId>kitchen2</externalId>
<externalCheckSum>checksum</externalCheckSum>
<videoId>5-Pcp7uSaZl1RGH1zc6ASA</videoId>
</common:attachment>

Example for URL

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<common:attachment xsi:type="common:Link" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" 
xmlns:ns3="http://rest.immobilienscout24.de/schema/platform/gis/1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<title>link test</title>
<externalId>kitchen2</externalId>
<externalCheckSum>checksum</externalCheckSum>
<url>http://youtube.de</url>
</common:attachment>

Requests (JSON)

Example for picture

{"common.attachment": {
@xmlns:{"common":"http:\/\/rest.immobilienscout24.de\/schema\/common\/1.0"},
"@xsi.type": "common:Picture",
"title": "Kochecke",
"externalId": "kitchen2",
"externalCheckSum": "your generated checksum",
"floorplan": "false",
"titlePicture": "false",
}}

Example for PDF

{"common.attachment": {
@xmlns:{"common":"http:\/\/rest.immobilienscout24.de\/schema\/common\/1.0"},
"@xsi.type": "common:PDFDocument",
"title": "Kochecke",
"externalId": "kitchen2",
"externalCheckSum": "your generated checksum",
"floorplan": "false",
}}

Example for streaming video with videoId

{"common.attachment": {
@xmlns:{"common":"http:\/\/rest.immobilienscout24.de\/schema\/common\/1.0"},
"@xsi.type": "common:StreamingVideo",
"title": "bla",
"externalId": "kitchen2",
"externalCheckSum": "checksum",
"videoId": "3C80Egv8mk0iyqElxY0t5Q"
}}

Example for URL

{"common.attachment": {
@xmlns:{"common":"http:\/\/rest.immobilienscout24.de\/schema\/common\/1.0"},
"@xsi.type": "common:Link",
"title": "urltitle",
"externalId": "kitchen2",
"externalCheckSum": "checksum",
"url": "http://test.de/abc",
}}

Response

The following section includes the HTTP status code, a short description and examples for the response body content of a successful processed request.
Error responses as well as other simple message responses are described in detail within the common message responses.

 

Status 201 Created

This status code is returned after a new entity of a resource was successfully created.

Header

Location Link to the newly created resource.

Body

XML

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<common:messages xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0"
    xmlns:xlink="http://www.w3.org/1999/xlink">
    <message>
        <messageCode>MESSAGE_RESOURCE_CREATED</messageCode>
        <message>Resource [attachment] with id [123456] has been created.</message>

        <id>123456</id>
    </message>
</common:messages>

 

 

JSON

 


{
  "common.messages":[
    {
      "message":{
        "messageCode":"MESSAGE_RESOURCE_CREATED",
        "message":"Resource [REALESTATE] with id [123456] has been created.",

        "id":123456
      }
    }
  ]
}