GuidesRequest an APPNewsletterContact UsChangelog
Guides

Publishing adverts

How to publish adverts

Overview

Publishing adverts is probably the main reason you're here for. By now you should have a registered application, know how to make requests, authorize users, advert payload, and validations that need to be in place to sends us a successful request. Let's see how to publish an Advert.

Basic workflow

To publish an advert you need the following information:

  • Advert data: The actual advert data (example below)
  • Site URN: The URN of the site where you are publishing the advert (check here the available sites)
  • Category URN: The category for your advert (check out the Taxonomy API)
  • Attribute URNs: Attributes make your advert more complete (also available in the Taxonomy API)

🚧

Imovirtual - Advert location

For Imovirtual Portugal, you can specify the advert location using either latitude/longitude coordinates or postal codes. If you provide both, the postal code will be ignored, and the coordinates will be used.

Note that sending coordinates doesn't mean that the exact location will be displayed — you need to use the exact field for that purpose (check Advert payload for a full description of the advert structure).

📘

Required fields

Note that depending on the category, certain fields are required for an advert to be valid. Make sure to check these rules here.

Publish payload example

You use the example below to test it out (you can also find it on our API Reference or check Advert validation rules:

{
  "title": "[qatest-mercury] Apartamento moderno em Cabanelas",
  "description": "Imóvel em Cabanelas com boa luminosidade, mobilado, 2 casas de banho. Este anúncio é um teste, não deve ser considerado.",
  "category_urn": "urn:concept:apartments-for-sale",
  "contact": {
    "name": "Joaquim Silva",
    "phone": "918888888",
    "email": "[email protected]",
    "photo": "https://i.imgur.com/9Em2tky.png"
  },
  "price": {
    "value": 123000,
    "currency": "EUR"
  },
  "location": {
    "lat": 41.573603,
    "lon": -7.214126,
    "exact": true
  },
  "images": [
    {
      "url": "https://i.imgur.com/WozSfdQg.jpg"
    },
    {
      "url": "https://i.imgur.com/3YNg1bI.jpg"
    }
  ],
  "movie_url": "https://www.youtube.com/watch?v=2me2WO6C1J8",
  "attributes": [
    {
      "urn": "urn:concept:area-m2",
      "value": "110"
    },
    {
      "urn": "urn:concept:price-negotiable",
      "value": "urn:concept:yes"
    },
    {
      "urn": "urn:concept:number-of-rooms",
      "value": "urn:concept:3"
    },
    {
      "urn": "urn:concept:characteristics",
      "value": "urn:concept:alarm"
    },
    {
      "urn": "urn:concept:characteristics",
      "value": "urn:concept:central-heating"
    }
  ],
  "site_urn": "urn:site:imovirtualcom",
  "custom_fields": {
    "id": "123456",
    "reference_id": "TEST1234"
  },
  "auto_extend": true
}

Making the API Request

Endpoint: POST https://api.olxgroup.com/advert/v1

With the payload saved in advert.json, the following request will publish the advert:

curl --location --request POST 'https://api.olxgroup.com/advert/v1'\
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <YOUR API KEY>' \
--header 'Authorization: Bearer <ACCESS TOKEN>' \
--header 'User-Agent: <CRM NAME>'
--data-raw @advert.json \

If all goes well, you should receive a Response with a 201 HTTP Status code, which looks like this:

{
    "transaction_id": "74c6bfc9-4163-11e8-a4a5-aff93b12a0c2",
    "message": "Data is valid",
    "data": {
        "uuid": "b195bdbc-9074-4bac-99a1-7248c0c98892",
        "last_action_status": "TO_POST"
    }
}

Great, you're almost there! To check if the request was successful, prepare the Webhook/Notification URL to handle notifications. Learn more about webhooks here.

Updated 9 months ago

See more

You published an advert but now you need to know what happened to it. Check out how to handle with notifications.