How to Post Classified Ads Automatically With Our API

Posting one ad through a form takes a few minutes. Posting fifty, and then changing a price on all of them next month, takes an afternoon nobody has. If your listings already live somewhere else — a property database, a course catalogue, a stock spreadsheet — typing them in again by hand is the slowest part of advertising here.

Every account on this site can post and manage its ads through an API instead. This guide explains what it does in plain terms, what your developer needs from you to set it up, and what it will not do for you.

What the API can do with your ads

The API covers everything you can do with your own listings in your account, without the browser:

• Create an ad with its title, description, price, category, location, photos and how long it should stay up.
• Edit an ad — a new price, a new description, more photos.
• Pause and reactivate an ad, for a property that is under offer or a course that is full.
• Delete an ad once the item is sold or the vacancy is filled.
• List your ads by status — active, paused, under review or rejected — with the view count and, for a rejected ad, the reason.

It works only on the ads that belong to your account. It cannot read other sellers’ listings or post on anyone else’s behalf, and it is free like the rest of the site.

Who should post classified ads automatically?

The API pays off when you have many listings that change often and already exist in another system. A property developer with forty units across three projects, a training institute with a new batch every month, a recruitment agency with vacancies opening and closing every week — each of them is copying data that a program could copy for them.

If you post a few ads a year, the form is faster than any integration. If you have many listings but no developer, look at Manage multiple ads in your account menu first: it creates and updates ads from a spreadsheet you fill in, with no programming at all.

Step 1: get an access token

The API identifies you by a token rather than a password on every request. Your developer asks for one by sending your account email, your password and a name for the device or program, such as “Property CRM”. The token comes back once; store it like a password.

A token can be limited to what the program needs. There are four permissions: reading ads, writing ads, uploading photos and deleting ads. A token that only creates and edits listings does not need the delete permission, and leaving it out means a bug in the program cannot remove your ads.

Tokens do not expire on their own. When a program is retired or a developer leaves, revoke its token through the API; the account password stays the same. Token requests are limited to five a minute for each email address.

Step 2: find your category and location IDs

The form lets you click through categories and type a city. The API wants numbers instead: one ID for the category and one for the location. Both come from lookup requests that need no token:

• the list of top-level categories, then the sub-categories under the one you pick, down to the deepest level — an ad must sit in a category with nothing below it;
• a country search by name, then a city search inside that country by name or postal code.

Look these up once, keep a small table that maps your own project names or branch offices to the IDs, and reuse it for every ad.

Step 3: upload the photos

Photos go up first, in one request of up to 12 images. JPEG, PNG, GIF and WebP are accepted, up to about 20 MB each and between 80 and 5,000 pixels on each side. The reply carries an upload batch ID, which the next step attaches to the ad.

The same rules apply as on the form: a phone number or website printed on an image is treated as contact details, so keep them off your photos. Photo uploads are limited to ten requests a minute.

Step 4: create the ad

The ad itself is one request with these fields:

1. Title, 10 to 120 characters, no emoji.
2. Description, 60 to 7,000 characters.
3. Price in US dollars, or the ad marked free — exactly one of the two. Convert a local price before you send it.
4. Category ID and location ID from step 2.
5. How long it stays up: one, two or three weeks, or one, three, six or nine months, or a year.
6. Optional: private or business seller, new or used, a link to your own page, and the photo batch ID from step 3.
7. For property, bedrooms, bathrooms and square feet; for vehicles, make, model and year.

The reply gives the new ad’s ID. Save it next to the record in your own system: every later edit, pause or delete uses it.

Does an API ad skip the checks?

No. An ad posted through the API is validated by the same rules as one posted through the form and goes through the same automatic review. A title that is too short, a price sent together with the free flag, or a category that still has sub-categories comes back at once with an error for that field, so your developer can fix it before the next run. Contact details in the text, duplicate listings and the other reasons covered in why service listings get refused and how to avoid it are applied exactly as they are on the form.

That matters most for bulk posting. Fifty near-identical ads with only the city changed are fifty duplicates, posted faster. Write each listing for what it actually offers, and let the API save you the typing, not the writing.

Keeping listings in step with your own system

Once the ad IDs are saved, keeping the site in step is a matter of small requests:

• Price change — edit the ad with the new price.
• Under offer, batch full, position on hold — pause it, and reactivate it if the deal falls through.
• Sold or filled — delete it, so buyers stop calling about something you no longer have.
• Weekly check — list your rejected ads and read the reason on each one.

Write requests are limited to 20 a minute. That is enough to post a large catalogue in one evening; spread a first import over a few minutes rather than firing it all at once. A status change can be refused for a moment while the ad is still being processed — retry it a little later. For property in particular, the guide for property developers and brokers covers what each listing should say.

Where to start

Post one ad through the form first, so you know which category and fields fit your listings. Then log in and open API Docs from your account menu. It lists every request with its fields and lets you try them in the browser. API Guide, next to it, links the raw specification file, which your developer can import into Postman or generate a client from. Start with one listing, check it on the site, and only then point the program at the whole catalogue.