Migrate existing integrations

Our marketplaces currently support different integrations across the markets we operate in. The new OLX Group API that you now have access to aims to standardize the way our partners connect to our sites in order to improve the overall experience of our end-users.

On this page, you can find more details about how to move away from an existing integration to the new Partner API with minimal effort and impact overall. If you're currently not our partner then this page is probably not relevant to you.

Take into account that before thinking about user migrations, your client implementation should be finished and ready for action. Check out the Before going live section to learn more. We'll go through this process together with you and validate everything before moving on to the next step.

By switching your integration from legacy integrations to RE Partner API you'll benefit from the numerous features we provide. The good news is that making the switch is easy and painless.

📘

Legacy vs API

When a client is migrated to the API, remember to remove them from all legacy integrations. Otherwise, clients can experience issues with their adverts.

Having access to the RE Partner API in itself is not enough as you won't be able to access adverts that were already published through legacy integrations. In order to link existing ads to your application, you can import adverts using a special flow described below.

Step 1 - User authorization

The first requirement for your client implementation is for you to include an extra parameter when calling our authorization URL: import=1. The final URL should be:

https://www.imovirtual.com/mercury/authorization/?response_type=code&client_id=<your-client-id>&state=<state-value>&import=1

When using this parameter, a successful user authorization will trigger a process on our side that will effectively link the user's existing ads to your application. From here on, you will have access to their metadata using the available endpoints.

When you do this, all of your client's adverts will be updated and the value of external_id will be set to a new uuid in our Marketplaces. You should recognize the external_id field from your legacy integration - it likely holds your own internal ID for each ad. But don't worry, you won't lose any data in this process.

📘

One time action!

Triggering the migration process is a one-time action. Once the adverts have been migrated, there is no need to reuse the &import=1 parameter during the next authorizations.

Step 2 - Sync ad IDs

❗️

Only active adverts posted through legacy import processes are claimed

Only active adverts posted through a legacy import process will be claimed and managed by the RE Partner API. Manually posted adverts and adverts already updated to one of the "inactive" status will not be claimed.

In order for your application to have access to all of those ads, you must update them on your side (in your own external_id field) with their new uuid. To accomplish this you should make a request our advert metadata endpoint and match the ads returned with those on your application/database using the field data.custom_fields.id as a matching key (this is where we saved the original external_id value):

{
  "data": [
    "uuid": "d62a77cf-b2c8-4487-973d-0e3751606383" // this is the newly generated UUID value stored in external_id
    "custom_fields": {
      "id": "123456", // this is the value stored previously in external_id
      "reference_id": "TEST1234"
    }
  ]
}

(payload is not complete for simplicity sake)

...and then update your own external_id with the uuid returned in each ad. Below is a simple diagram to illustrate the process:

Once this step is finished your application has full access to all of the user's ads.

The final step is to perform an update of all adverts (PUT) to synchronise them. Executing this step will give you the assurance that the adverts exported to the portal match the adverts stored on your site.

📘

What happens to the user's ads posted through a legacy integration?

We recommend that after finishing this process you remove the user's ads from your legacy integration and deactivate the legacy export. It is very important to send the adverts only via API (to avoid duplicates).