One of the most important aspects of integrating your application with our API is the syncing of adverts and their status. To accomplish this, your application must implement the necessary business logic so that the right operations are executed according to the situation.

Advert operations and statuses

Our API isn't very restrictive in terms of which operations you can and cannot execute. There are a few important things to keep in mind though. One important reference to have is the Advert status codes page where you can see the different statuses an ad can have during its lifecycle.

Keep in mind the following aspects:

• Any operation that targets an advert that is in a transient state (TO_POST, TO_PUT, TO_DELETE, TO_ACTIVATE, and TO_DEACTIVATE), will be rejected. This restriction is in place as a control mechanism to ensure a sort of transaction. See below the example of an acknowledge notification:

{
  "transaction_id": "516afb52-ce15-4920-82f2-519dcb169159",
  "message": "Illegal status change"
}

To see more which operations can be executed for each code(advert status), take a look at Publish Advert page.

📘

Adverts stuck in a limbo

It might happen that an advert gets stuck in a transient state for a longer time than expected. This can happen for multiple reasons. Therefore our system expires ads in such states after 3 hours.

How to keep things in sync

Webhooks

To make it all work properly you must implement webhooks. This way you'll always have the latest advert statuses on your side. As a safety mechanism, you can also use the metadata API, although we don't recommend that you rely solely on it through long-polling. Webhooks are cool, use them!

📘

Use Case - Advert status change is originated outside of your app

The importance of webhooks becomes more obvious when you know that an advert status change can be originated outside of your own application, by someone other than its "owner". There are two cases where this can happen:

1. The advert is deactivated due to ad expiry
When the ad reaches its end date, the system automatically deactivates it. This automated process triggers a notification to your application's callback URL informing it of the advert status change.

2. The advert is removed by someone from our internal quality or support teams
A member of our team can remove an ad due to non-compliance with quality rules or by customer request. This type of change also triggers an advert_lifecycle notification to your application.

See more information at Advert Lifecycle.

Note: Users who have granted your application access to their accounts, are not allowed to edit or remove ads directly from their own "My Account". They can only manage their ads from your application while the authorization is active (they can revoke it at any time).

Handling UUIDs

The UUID that we provide to you for each advert is very important since this is the key that links items in your application to adverts published on our side.

For example, whenever a user unpublishes an advert from your application (which you should execute as a DELETE operation), you must know that this UUID cannot be used anymore. Once an advert is removed on our side, you won't be able to update it any longer. If the user decides to re-publish this advert, then you should execute a POST and not a PUT, so that you get a new UUID.

Below you can see an illustration of a similar scenario in which a user publishes an ad for the first time, then removes the publication and finally updates it for publication again. In the diagram you can see how your implementation should handle the different operations and ad statuses received through webhooks.